POST /v1/stations/enrich-distances

Annotate stations with route-relative distance and detour information

POST /v1/stations/enrich-distances

Compute route-relative distance and detour time for stations

cURL

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,
      "fuel_type": "regular",
      "miles_from_route_start": 1,
      "detour_minutes": 1,
      "metadata": {}
    }
  ],
  "coarse_filter_radius_miles": 7,
  "max_detour_minutes": 10
}
'

200

{
  "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.

Show child attributes

stations · Station · object[] · required

Required array length: 1 - 5000 elements

Show child attributes

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

200

application/json

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

stations · Station · object[] · required

Show child attributes

request_id · string · required

warnings · string[]