Skip to main content
POST
/
v1
/
stations
/
enrich-distances
Compute route-relative distance and detour time for stations
curl --request POST \
  --url https://api.example.com/v1/stations/enrich-distances \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "route": {
    "total_distance_miles": 123,
    "total_duration_minutes": 123,
    "start": {
      "lat": 0,
      "lng": 0
    },
    "end": {
      "lat": 0,
      "lng": 0
    },
    "polyline": "<string>",
    "waypoints": [
      {
        "lat": 0,
        "lng": 0
      }
    ]
  },
  "stations": [
    {
      "id": "<string>",
      "name": "<string>",
      "address": "<string>",
      "location": {
        "lat": 0,
        "lng": 0
      },
      "brand": "<string>",
      "price_per_gallon": 50,
      "miles_from_route_start": 1,
      "detour_minutes": 1,
      "metadata": {}
    }
  ],
  "coarse_filter_radius_miles": 7,
  "max_detour_minutes": 10
}
'
{
  "stations": [
    {
      "id": "partner_xyz_001",
      "name": "Pilot Travel Center",
      "address": "456 Truck Rd, Flagstaff, AZ",
      "location": {
        "lat": 35.1983,
        "lng": -111.6513
      },
      "brand": "Pilot",
      "price_per_gallon": 4.29,
      "fuel_type": "diesel",
      "miles_from_route_start": 487.3,
      "detour_minutes": 3.2
    }
  ],
  "warnings": [
    "5 stations dropped: more than 7.0 miles from the route."
  ],
  "request_id": "req_def789ghi012"
}
The /v1/stations/enrich-distances endpoint takes a route and a list of stations, returning the same stations with miles_from_route_start and detour_minutes populated for each station that passes the filter thresholds.

​
When to Use

Required before /v1/optimize if your station data doesn’t already include route-relative distances. If you compute these values in your own systems, you can skip this endpoint and pass enriched stations directly to /v1/optimize.

​
Filters

Two filters control which stations are returned:
  • Coarse radius filter (coarse_filter_radius_miles, default 7): stations farther than this from the route polyline are dropped without matrix routing calls. Reduces cost.
  • Max detour filter (max_detour_minutes, default 10): stations whose round-trip detour exceeds this threshold are dropped after matrix routing.

​
Behavior

  • Partner-provided IDs and metadata are preserved unchanged in the response
  • Stations dropped by filters are excluded from the response (not returned with null values)
  • The response includes a count of stations dropped at each filter stage for debugging

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
route
Route · object
required

Internal route representation. Flat shape — upstream adapters normalize Google/Mapbox responses into this before it hits B2B code.

​
stations
Station · object[]
required
Required array length: 1 - 5000 elements
​
coarse_filter_radius_miles
number
default:7

Stations more than this many miles from the route polyline are dropped before the (expensive) distance matrix call. Bounds protect against runaway matrix costs. Increase for more lenient inclusion if your station coordinates are loose; decrease to cut matrix-call costs.

Required range: 5 <= x <= 20
​
max_detour_minutes
number
default:10

Stations whose round-trip detour exceeds this many minutes are dropped after the matrix call.

Required range: 1 <= x <= 20

Response

Stations enriched. Some may be filtered out; see the warnings field.

​
stations
Station · object[]
required
​
request_id
string
required
​
warnings
string[]