BestConnect Travel API

Getting started

Three calls cover the whole service. GET /health needs no key and tells you the service is up and which calculator version it is running. GET /v1/openapi.json is the machine-readable specification. POST /v1/travel does the work.

curl -s https://api-demo.best-ts.com.au/v1/travel \
  -H "Authorization: Bearer $TRAVEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sites":[{"reference":"SITE-001","suburb":"North Sydney","postcode":"2060"}]}'

Replace the key with the one Best Technology Services issued to you. Keys are environment-specific: a demo key does not work in production.

Authentication

Every call to /v1/travel carries an API key, in either header form:

Call the API from your server, never from a browser, so the key stays out of client code. Keys can be rotated on request: a new key is issued, both work for an agreed period, then the old one is retired. A missing or unknown key returns 401.

Cost travel for a list of sites

The body is a JSON object with exactly one of sites or text, and an optional unitRate.

Request

{
  "unitRate": 390,
  "sites": [
    { "reference": "SITE-001", "suburb": "North Sydney", "postcode": "2060", "state": "NSW" },
    { "reference": "SITE-002", "suburb": "Mudgee",       "postcode": "2850" },
    { "reference": "SITE-003", "suburb": "Coober Pedy",  "postcode": "5723", "state": "SA" }
  ]
}

Response

{
  "requestId": "6f1c0a3e-...",
  "calculator": { "api": "v1", "appVersion": "2.16.9", "ratesReviewed": "2026-08-15", "environment": "demo" },
  "unitRate": 390,
  "sites": [
    {
      "reference": "SITE-001",
      "input": { "suburb": "North Sydney", "postcode": "2060", "state": "NSW" },
      "pop": "Sydney", "zone": "METRO", "km": 0, "driveHours": 0,
      "bcUnits": 0, "zoneUpliftUnits": 0, "matchType": "exact",
      "flyIn": false, "regionalPlus": false, "review": false, "error": false,
      "notes": ""
    },
    {
      "reference": "SITE-002",
      "input": { "suburb": "Mudgee", "postcode": "2850" },
      "pop": "Dubbo", "zone": "REGIONAL+", "km": 140, "driveHours": 1.75,
      "bcUnits": 0.5, "zoneUpliftUnits": 0.25, "matchType": "exact",
      "flyIn": false, "regionalPlus": true, "review": false, "error": false,
      "notes": "Regional+ — beyond 100km of a regional PoP"
    },
    {
      "reference": "SITE-003",
      "input": { "suburb": "Coober Pedy", "postcode": "5723", "state": "SA" },
      "pop": "FLY-IN", "zone": "FLY-IN", "km": 850, "driveHours": null,
      "bcUnits": 7.75, "zoneUpliftUnits": 0, "matchType": "exact",
      "flyIn": true, "regionalPlus": false, "review": false, "error": false,
      "flyInDetail": {
        "airport": "CPD", "airportName": "Coober Pedy", "originPop": "Adelaide",
        "flightHours": 1.6, "airportKm": 10, "fareClass": "REGIONAL", "nightsClass": "REGIONAL",
        "fareAllowance": 650, "nights": 1, "travelHours": 10, "passSales": 1171.5
      },
      "notes": "Fly-in Adelaide to Coober Pedy (Regional, 1.6h), 10 km from airport, 1 night(s) at 1 unit: 10.0h travel on the day-rate ladder + $1171.50 pass-through incl. $650 fare"
    }
  ],
  "summary": {
    "totalSites": 3, "matched": 3, "notFound": 0, "mismatch": 0, "errorCount": 0,
    "flyIn": 1, "reviewCount": 0, "regionalPlus": 1,
    "byZone": { "METRO": 1, "REGIONAL": 0, "REGIONAL+": 1, "REMOTE": 0, "DRIVE-OVERNIGHT": 0, "FLY-IN": 1 },
    "totalBcUnits": 8.25, "zoneUpliftUnits": 0.25, "exGst": 3217.5, "gst": 321.75, "incGst": 3539.25
  }
}

Abridged from a real demo response. Results come back in input order, one per site; a site inside its PoP's included distance returns zero units and an empty notes. The header X-Request-Id carries the same id as the body.

Response fields

Each site

Summary

Zones

The zone follows from the dispatching PoP's class and the road drive time. Distances and zones are precomputed from real road routing and never estimated on the fly.

Travel beyond the PoP's included distance (60 km from a metro PoP, 100 km regional, 20 km remote) accrues in quarter-unit steps per started 20 km. Regional and remote attendances also carry a zone uplift, returned separately as zoneUpliftUnits. The notes field on each site spells out the working.

Errors

Every error is JSON with the same shape. details appears on validation failures and names each offending field by JSON path.

{
  "error": {
    "code": "validation_failed",
    "message": "The request did not pass validation.",
    "requestId": "6f1c0a3e-...",
    "details": [
      { "path": "sites[1].postcode", "message": "postcode is required." }
    ]
  }
}

A 400 never means the sites were wrong, only the request. Address problems come back as 200 with error: true on the affected sites, so one bad address does not fail the whole list.

Limits and reliability

• Up to 500 sites per request and a body of at most 1 MB. Split larger lists.
• 120 requests per minute per key. The headers X-RateLimit-Limit and X-RateLimit-Remaining are on every priced response.
• The service is always on and holds its reference data in memory. A warm request for a hundred sites typically returns in tens of milliseconds plus network time.
• Calls are idempotent. Retry on a network failure or a 500 with the same body, and reuse your X-Request-Id so both attempts are traceable to one call.
• This is the demo service. It runs the current calculator and rate table but may be reset or redeployed without notice. Production has its own base URL and key.

Changes and support

The path carries the major version. Additive changes (new optional fields, new zones) ship within v1 without notice; anything that would change the meaning of an existing field ships as v2 alongside v1, with at least three months before v1 is retired. The calculator version and the date the rates were last reviewed are on every response, so you can tell when the figures moved.

Questions, keys and problem reports: info@best-ts.com.au, or your Best Technology Services contact. Include the requestId.

Consider it done.