Pricing API reference

One HTTPS + JSON API that tells your website or app whether a trip is serviceable and exactly what it costs. Any language that can send an HTTPS request can integrate.

Send coordinates, a vehicle code and a service type. The engine checks the pickup against geofenced service areas, applies outstation route rules, picks the live pricing version and returns an itemised fare with a quote ID. The engine is the source of truth for price — requests that include a fare are rejected.

Base URL   https://api.primetaxihub.com/api/v1
Format     JSON (UTF-8), request body ≤ 32 KB
Timezone   Send pickup_at as ISO-8601 with offset. Night/peak/weekend rules use the pickup's local time.

Every request except /health needs your API key in the Authorization header (or X-API-Key):

Authorization: Bearer pth_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are issued per client in the admin console and shown once. Keep them on your server. If a key is ever exposed in browser code or a repository, revoke it and issue a new one. Clients can additionally be restricted to IP addresses and browser origins.

If your client has Require HMAC signature enabled, add two headers. The signature is hex(HMAC-SHA256(api_secret, timestamp + "." + raw_body)); timestamps older than 5 minutes are rejected, which blocks replays.

import crypto from "node:crypto";

const body = JSON.stringify(payload);
const ts = Math.floor(Date.now() / 1000).toString();
const sig = crypto.createHmac("sha256", process.env.PTH_API_SECRET).update(`${ts}.${body}`).digest("hex");

await fetch("https://api.primetaxihub.com/api/v1/fare/quote", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PTH_API_KEY}`,
    "Content-Type": "application/json",
    "X-PTH-Timestamp": ts,
    "X-PTH-Signature": sig,
  },
  body, // send exactly the string you signed
});

POST /fare/quote

{
  "pickup": { "lat": 28.6139, "lng": 77.2090, "address": "Connaught Place" },
  "drop":   { "lat": 28.4595, "lng": 77.0266 },
  "vehicle": "sedan",
  "service_type": "local",
  "trip_type": "one_way",
  "pickup_at": "2026-10-10T09:30:00+05:30",
  "coupon_code": "WELCOME10"
}

Response:

{
  "success": true,
  "quote_id": "QT-20261003-000001",
  "currency": "INR",
  "expires_at": "2026-10-03T09:30:00.000Z",
  "pickup_at": "2026-10-10T04:00:00.000Z",
  "service": { "type": "local", "name": "Local", "trip_type": "one_way" },
  "vehicle": { "code": "sedan", "name": "Sedan", "passenger_capacity": 4, "luggage_capacity": 2, "image_url": null },
  "location": { "pickup_area": "Delhi NCR", "drop_area": "Delhi NCR", "pickup_allowed": true, "drop_allowed": true,
                "pickup_airport": null, "drop_airport": null },
  "route": null,
  "distance": { "km": 28.4, "billable": 28.4, "unit": "KM", "duration_minutes": 72, "estimated": false },
  "pricing": { "plan": "delhi_local_sedan", "version": 2 },
  "fare": {
    "base_fare": 2500, "included_km": 80, "extra_km": 0, "extra_km_charge": 0,
    "time_charge": 0, "waiting_charge": 0, "airport_charge": 0, "night_charge": 0, "surcharge": 0,
    "toll": 0, "parking": 0, "state_tax": 0, "driver_allowance": 0, "other_charges": 0,
    "adjustments": 0, "discount": 200, "subtotal": 2300,
    "tax": 115, "taxes": [{ "name": "GST", "rate": 5, "type": "PERCENTAGE", "amount": 115 }],
    "round_off": 0, "total": 2415, "trip_days": 1
  },
  "warnings": [],
  "request_id": "6c1b2f7e-…"
}

Quotes expire (default 30 minutes). Store quote_id with the booking and call /quote/{id}/verify before confirming.

Every error uses the same envelope and an HTTP status that matches the problem:

{
  "success": false,
  "error": { "code": "OUTSIDE_SERVICE_AREA", "message": "Pickup location is outside our service area." },
  "request_id": "…"
}

Each client has a per-minute limit (default 60). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit you get 429 RATE_LIMIT_EXCEEDED with Retry-After. Ask your account manager to raise the limit.

• Keep the API key and secret on your server; the browser talks to your backend.
• Show the fare from the response exactly — never compute or round it yourself.
• Save quote_id with the booking and verify it before confirming payment.
• Handle OUTSIDE_SERVICE_AREA, ROUTE_NOT_ALLOWED and VEHICLE_NOT_AVAILABLE with clear messages to your customer.
• Log request_id from every response; support uses it to find the exact calculation.
• Retry 429 and 5xx with backoff. Don't retry 4xx validation errors unchanged.