Skip to main content

Route All Ep

POST 
/v1/route/all

Route All

Retrieves the route lanes shown in Route Management, as JSON. One record is returned per origin/destination lane — the one in effect today, unless effective_between asks for history, in which case a lane appears once per effective-dated record (see the ordering note under routes). Each record carries the map-service estimate, any override, and the effective value that results.

note

A lane is returned when the map service has successfully routed it, or when it carries any manually entered override (distance, time, payroll or toll). Lanes the map service could not route or has not yet processed, and that have no override, are omitted. Use api_verified to tell routed lanes from override-only ones.

Required Scopes (ia.r)

Results are paged. Request up to limit records at a time, then pass the returned next_cursor back as cursor for the following page. Keep going until next_cursor is null. Send the same filters with every page — the cursor carries your position, not your query.

Request​

location_ids: list[str] = []
Only return lanes with one of these locations at either end. Leave empty for every location. Use the id from /location/all.

markets: list[str] = []
Only return lanes with a location in one of these markets at either end. Leave empty for every market. Market names come from /market/all.

effective_between: DateWindow | None = None
Which effective-dated records to return. Omit it for the record in effect today — the usual case. Supply it to read history instead; a bound left unset is unbounded, so {} returns every record ever held for the matching lanes.

effective_between.from_date: datetime | None = None
Return records still in effect on or after this date. Unset means no lower bound.

effective_between.to_date: datetime | None = None
Return records that took effect on or before this date. Unset means no upper bound.

Only the date part of either bound is used, and a supplied UTC offset is honoured — a timestamp is read as the calendar date it falls on in your offset, not in UTC. For a single point in time, set both bounds to it.

has_toll: bool | None = None
Omit (or send null) for every lane. true returns only lanes that have a toll; false only lanes that do not. A lane "has a toll" when its effective toll is a non-zero number — so an override of 0 means no toll even when the map service returned one, matching how the toll is reported in toll.

as_of: datetime | None = None
Only return records changed at or after this instant — the filter for an incremental pull. Omit it for every record. Unlike effective_between this is a point in time rather than a calendar date: the whole timestamp is compared, an offset is honoured, and a value sent without one is read as UTC.

note

A record whose change timestamp was never set is never returned by an as_of pull. Creating a lane stamps it, so new lanes do appear. But a few internal maintenance paths change a record without restamping it — a location rename or a coordinate move, and the background map-service verification that makes a lane with no override eligible for this endpoint. A lane can therefore enter the result set, or have its origin/destination labels or coordinates change, without updated_on moving. Re-run a full unfiltered pull periodically if the sync has to be exact.

limit: int = 5000
Maximum records to return. Between 1 and 10000.

cursor: str | None = None
Continuation token. Omit it for the first page; after that pass the next_cursor from the previous response. Treat it as opaque — its contents are an implementation detail and may change between releases.

note

location_ids and markets are combined with AND — supplying both returns only lanes matching a location and a market. Values inside one filter are combined with OR.

Response​

routes: list[RouteView]
The matching route lanes, in the order the records were created. Paging follows that order by position rather than by a record count, so a route created or deleted while you are paging cannot cause a record to be repeated or skipped.

note

The ordering is stable but carries no business meaning — it is not sorted by origin, destination, or date, and a lane's records are not grouped together. When effective_between is supplied a lane appears once per effective-dated record, and those records may land anywhere in the result, on any page. To reassemble one lane's history, collect rows across the whole result set and group them yourself on origin_location_id + destination_location_id.

note

Each page reflects the data as of that request rather than a single point in time. A route created or deleted mid-walk is not repeated or skipped, but a record changed after you passed it is not revisited. For a pull that has to be exact, re-run it if route data changed mid-pull.

routes[].id: str
Internal identifier for the route record.

routes[].origin: str
Identifies the origin. This is the store number when the origin is a store, and the terminal name when it is a terminal. It matches the origin column of the Route Management Excel export.

routes[].origin_location_id: str
Internal identifier for the origin location. Matches id from /location/all.

routes[].origin_location_name: str | None
Display name of the origin location. Null if the location is no longer in the system.

routes[].origin_location_type: str
Type of the origin — Terminal, Depot, Store, and so on.

routes[].origin_lat: float
Latitude of the origin, to four decimal places.

routes[].origin_lon: float
Longitude of the origin, to four decimal places.

routes[].origin_city: str | None
City of the origin location.

routes[].origin_state: str | None
State of the origin location.

routes[].origin_market: str | None
Market the origin location belongs to.

routes[].destination, routes[].destination_location_id, routes[].destination_location_name, routes[].destination_location_type, routes[].destination_lat, routes[].destination_lon, routes[].destination_city, routes[].destination_state, routes[].destination_market
The same nine fields for the destination end of the lane.

routes[].effective_from: datetime
Calendar date this record takes effect. No timezone applies — do not convert it.

routes[].effective_to: datetime | None
Calendar date this record stops being effective. Null means it is still in effect. No timezone applies.

routes[].distance_miles: float | None
Distance actually used for this lane. This is override_distance_miles when one is set, otherwise api_distance_miles — so it is -1 for a lane the map service could not route and that has no distance override. Null when neither exists.

routes[].api_distance_miles: float | None
Distance calculated by the map service. Null when it has not been calculated, and -1 when the map service could not route the lane. See api_verified.

routes[].override_distance_miles: float | None
Manually entered distance for this lane. Null when no override is set.

routes[].haversine_distance_miles: float
Straight-line distance between the two points. Always present, and always a geometric figure rather than a driving distance.

routes[].travel_time_minutes: float | None
Travel time actually used for this lane, in whole minutes. This is override_travel_time_minutes when one is set, otherwise api_travel_time_minutes — so it is -1 for a lane the map service could not route and that has no time override. Null when neither exists.

routes[].api_travel_time_minutes: float | None
Travel time calculated by the map service, in whole minutes. -1 when the map service could not route the lane.

routes[].override_travel_time_minutes: float | None
Manually entered travel time, in whole minutes. Null when no override is set.

routes[].toll: float | None
Toll actually charged on this lane. This is override_toll when one is set, otherwise api_toll. Null means no toll applies.

routes[].api_toll: float | None
Toll returned by the map service.

routes[].override_toll: float | None
Manually entered toll. Unlike the other overrides, 0 is meaningful here — it waives the toll and takes precedence over a non-zero api_toll.

routes[].override_payroll_miles: float | None
Manually entered miles used for driver pay on this lane, when it differs from the driving distance.

routes[].override_payroll_minutes: float | None
Manually entered minutes used for driver pay on this lane, when it differs from the travel time.

routes[].api_verified: bool | None
Whether the map service routed the lane. true for a routed lane; false or null for a lane returned only because it carries an override, in which case the api_* values are null (not yet calculated) or -1 (could not be routed), and only the overridden values are usable.

routes[].created_on: datetime | None
When the record was created (UTC).

routes[].updated_on: datetime | None
When the record was last changed (UTC).

routes[].updated_by: str | None
Who last changed the record. Gravitate for system-driven refreshes.

next_cursor: str | None
Pass back as cursor to fetch the next page. null means this was the last page — there is no separate "has more" flag to reconcile against it.

errors: list[str]
One message per unknown location id or market name in the request. Matching records are still returned, so check this to tell a typo apart from a genuinely empty result.

Errors​

422 — effective_between.from_date is later than to_date. Such a window can never match, so it is rejected rather than answered with an empty list.

422 — cursor is not a token produced by this endpoint. A cursor from an older release may also be rejected this way; start the walk again from the first page.

Unknown location_ids and markets are reported in errors instead, not as a 422.

Responses​

Successful Response

{
  "routes": [
    {
      "id": "string",
      "origin": "string",
      "origin_location_id": "string",
      "origin_location_name": "string",
      "origin_location_type": "Biodiesel Terminal",
      "origin_lat": 0,
      "origin_lon": 0,
      "origin_city": "string",
      "origin_state": "string",
      "origin_market": "string",
      "destination": "string",
      "destination_location_id": "string",
      "destination_location_name": "string",
      "destination_location_type": "Biodiesel Terminal",
      "destination_lat": 0,
      "destination_lon": 0,
      "destination_city": "string",
      "destination_state": "string",
      "destination_market": "string",
      "effective_from": "2026-11-11T17:36:45.819Z",
      "effective_to": "2026-11-11T17:36:45.819Z",
      "distance_miles": 0,
      "api_distance_miles": 0,
      "override_distance_miles": 0,
      "haversine_distance_miles": 0,
      "travel_time_minutes": 0,
      "api_travel_time_minutes": 0,
      "override_travel_time_minutes": 0,
      "toll": 0,
      "api_toll": 0,
      "override_toll": 0,
      "override_payroll_miles": 0,
      "override_payroll_minutes": 0,
      "api_verified": true,
      "created_on": "2026-11-11T17:36:45.819Z",
      "updated_on": "2026-11-11T17:36:45.819Z",
      "updated_by": "string"
    }
  ],
  "next_cursor": "string",
  "errors": [
    "string"
  ]
}
Loading...