fastroute API

API reference

The API speaks JSON over HTTP.

EndpointPurpose
POST /v1/plansPlan a day and return the Pareto front.
POST /v1/addressesSay what addresses are understood as, without planning.
POST /v1/geometryReturn the line of one route along the roads, for drawing it on a map.
GET /healthReport that the service is up and how it is configured.
GET /docsThis reference as a web page.

Conventions used throughout:

Keys

On a server that is open to customers, every request to /v1 needs a key:

Authorization: Bearer fr_live_...

A key is made on the customer's page in the web app, where it is shown once. It goes in this header only, never in an address. A request without a valid key gets 401 unauthorized.

Each customer has three limits, shown on that page: requests per minute (429 rate_limited with a Retry-After header when used up), plans computed at the same time (further ones wait briefly, then 503 busy), and stops per planning request (400 invalid_request).

What is counted per key and day: requests, plans, stops, refused requests, and how many different workers were planned. A worker is told apart by the id it is sent with; what is kept is a fingerprint of that id, not the id. Addresses and coordinates are not kept.

A server without a key database, such as a demo behind its own password, accepts requests without a key. GET /health never needs one.

POST /v1/plans

Request

{
  "stops": [
    { "id": "oper", "location": { "address": "Opernring 2, 1010 Wien" }, "service_seconds": 1800,
      "appointment": { "start": "10:00", "end": "10:15" } },
    { "id": "schoenbrunn", "location": { "address": "Schönbrunner Schloßstraße 47, 1130 Wien" }, "service_seconds": 2700,
      "preferred": { "start": "08:00", "end": "09:30" } },
    { "id": "donauzentrum", "location": { "lat": 48.2430, "lon": 16.4347 }, "service_seconds": 1200 }
  ],
  "workers": [
    { "id": "anna", "start": { "address": "Stephansplatz 1, 1010 Wien" }, "shift": { "start": "08:00", "end": "17:00" } }
  ]
}

stops[]

FieldRequiredMeaning
idyesYour name for the stop. Non-empty, unique among stops.
locationyesWhere it is; see Locations.
service_secondsno, default 0Time spent on site.
appointmentno{start, end}. Work must begin inside this window. Never violated: a plan that cannot keep it is not returned.
preferredno{start, end}. Work does not begin before start. Beginning after end is allowed and counts as lateness.

A stop may have both windows. For an appointment at exactly 10:00, use the same time for start and end, or leave a tolerance such as 10:00 to 10:15.

Every stop is planned, unless options.allow_unplanned says that stops may be left out when not all of them fit; see Stops that do not fit.

workers[]

A worker is one person or vehicle that drives a route.

FieldRequiredMeaning
idyesYour name for the worker. Non-empty, unique among workers.
startyesWhere the route begins; see Locations.
endno, default startWhere the route ends.
shiftyes{start, end}. The worker leaves no earlier than start and is back no later than end.
breakno{earliest, latest, seconds}. A pause of seconds, such as lunch, that should begin between earliest and latest; see Breaks.

A worker may end up with no stops. The number of workers is an input, not something the solver minimises.

Locations

A location is given in exactly one of two ways:

{ "lat": 48.2430, "lon": 16.4347 }
{ "address": "Opernring 2, 1010 Wien" }

Addresses need a geocoder configured on the server (GET /health tells you) and must contain a house number and a postcode or town. How they are matched, and why some are refused, is described under Addresses.

objectives[] (optional)

Which objectives span the front. All are minimised. The default is drive_time, lateness, longest_day.

kindUnitMeaningDefault resolution
drive_timesecondsTotal time on the road, all workers.60
distancemetresTotal distance driven, all workers.100
latenesssecondsTotal lateness against preferred windows.60
longest_daysecondsThe longest working day among the workers. Minimising it balances the workload.60
"objectives": [ { "kind": "distance", "resolution": 500 }, { "kind": "lateness" } ]

resolution is the step in which two plans count as equal in that objective. With 60, plans whose drive times fall in the same minute are not told apart. Without it a front fills up with plans that differ by a few seconds. Larger steps give smaller fronts; 1 compares exactly.

Each added objective makes the front larger and the search slower. Two or three is a good number.

options (optional)

FieldDefaultMeaning
time_limit_ms3000Search budget, 1 to 120000. The default suits days of up to about 50 stops; give larger days more, up to the full two minutes from about 150 stops.
iterationsunlimitedFixed number of search iterations. Given without time_limit_ms, the result is repeatable for a seed, as long as the run stays under the 120 s cap.
seed1Seed of the search's random choices.
address_precision"house""street" accepts a point on the street when the house number is not in the map.
allow_unplannedfalsetrue: when not every stop fits, plans leave out as few as possible and say which; see Stops that do not fit. false: such a day gets no_feasible_plan.
time_of_day"weekday" with road travel times"weekday": trips in towns take longer in the rush hours of a working day and less at night; see Rush hours. "off": every trip takes its average duration whenever it starts. With straight-line estimates the default is "off".

Small requests (up to 7 stops and 4 workers) are solved exactly and ignore the search options.

Response

For the request above, shortened to the first of two plans and two of three geocoded entries:

{
  "method": "exact",
  "travel_times": "osrm",
  "time_of_day": "weekday",
  "objectives": [
    { "kind": "drive_time", "unit": "seconds", "resolution": 60 },
    { "kind": "lateness", "unit": "seconds", "resolution": 60 },
    { "kind": "longest_day", "unit": "seconds", "resolution": 60 }
  ],
  "plans": [
    {
      "values": { "drive_time": 5059, "lateness": 4912, "longest_day": 10759 },
      "routes": [
        {
          "worker": "anna",
          "start": "09:52:11",
          "end": "12:51:30",
          "drive_seconds": 5059,
          "distance_metres": 38270,
          "lateness_seconds": 4912,
          "waiting_seconds": 0,
          "visits": [
            { "stop": "oper", "arrival": "10:00:00", "begin": "10:00:00", "departure": "10:30:00" },
            { "stop": "schoenbrunn", "arrival": "10:51:52", "begin": "10:51:52", "departure": "11:36:52" },
            { "stop": "donauzentrum", "arrival": "12:11:05", "begin": "12:11:05", "departure": "12:31:05" }
          ]
        }
      ]
    }
  ],
  "representatives": { "balanced": 1, "min_drive_time": 0, "min_lateness": 1, "min_longest_day": 0 },
  "geocoded": [
    { "owner": "worker anna (start)", "address": "Stephansplatz 1, 1010 Wien",
      "matched": "Stephansplatz 1, 1010 Wien",
      "location": { "lat": 48.2081643, "lon": 16.3734772 }, "precision": "house" },
    { "owner": "stop oper", "address": "Opernring 2, 1010 Wien",
      "matched": "Opernring 2, 1010 Wien",
      "location": { "lat": 48.2032864, "lon": 16.3691936 }, "precision": "house" }
  ],
  "locations": {
    "stops": {
      "oper": { "lat": 48.2032864, "lon": 16.3691936 },
      "schoenbrunn": { "lat": 48.1849894, "lon": 16.3115684 },
      "donauzentrum": { "lat": 48.243, "lon": 16.4347 }
    },
    "workers": {
      "anna": { "start": { "lat": 48.2081643, "lon": 16.3734772 }, "end": { "lat": 48.2081643, "lon": 16.3734772 } }
    }
  },
  "timing": { "geocoding_ms": 563, "travel_times_ms": 19, "solve_ms": 0 }
}
FieldMeaning
method"exact": the true Pareto front. "search": an approximation of it.
travel_times"osrm": road network. "straight_line": estimate without a map, for development only.
time_of_day"weekday": the plans were timed with rush hours. "off": they were not.
objectivesThe objectives used, with units and resolutions.
plansThe front, sorted by objective values. No plan in it is at least as good as another in every objective.
plans[].valuesThe plan's value in each objective, unrounded.
plans[].routesOne entry per worker who has stops. Workers without stops are left out.
plans[].unplannedOnly with allow_unplanned, and only when stops are left out: each with its stop and a reason.
representativesIndices into plans worth showing first; see below.
geocodedWhat each address in the request was understood as. Absent if the request had no addresses.
locationsThe coordinates every stop and worker was planned with, by id, whether they were sent or looked up. Enough to put a plan on a map.
timingMilliseconds spent locating addresses, fetching travel times and solving. With method search also iterations: how many search iterations were run before the time limit or the requested count was reached. A large request under the default time limit gets few.

Routes and visits

FieldMeaning
start, endWhen the worker leaves the start location and arrives at the end location.
drive_seconds, distance_metresDriving on this route, including the way back.
lateness_secondsLateness against preferred windows on this route.
waiting_secondsIdle time before stops on this route.
break{start, end}: when the worker's break falls. Absent if the worker has none or the route gives no occasion for one.
visits[].arrivalWhen the worker reaches the stop.
visits[].beginWhen work begins: the arrival, or the start of the stop's window if that is later.
visits[].departurebegin plus the service time.

A worker who would have to wait at the first stop leaves later instead. That is why start in the example is 09:52 although the shift begins at 08:00, and why waiting at the first stop never shows up in waiting_seconds.

Breaks

{ "id": "anna", "start": { "address": "Stephansplatz 1, 1010 Wien" },
  "shift": { "start": "08:00", "end": "17:00" },
  "break": { "earliest": "11:30", "latest": "13:00", "seconds": 1800 } }

A worker with a break takes it between two jobs, never in the middle of a drive or a job:

The break lengthens the working day and counts neither as driving nor as waiting. A worker who sets out at or after earliest takes none, nor one whose jobs are all done before it; after the last job the worker drives home. A break that is due is not dropped for an appointment: a route that cannot hold both is not planned. A single job that runs from before earliest past latest is not interrupted, and the break follows it; so latest is kept wherever the jobs allow, and is not a guarantee.

seconds is between 60 and 14400.

Stops that do not fit

Without allow_unplanned, a day with more work than the workers can do in their shifts, or with an appointment nobody can keep, has no plan and is answered with 422 no_feasible_plan.

With allow_unplanned, such a day is planned as far as it goes:

reasonMeaning
day_fullThe stop would fit on its own, but not together with the rest.
appointment_out_of_reachNo worker can be there inside the appointment, even with nothing else to do.
out_of_reachThe stop alone does not fit into any worker's shift: too far away, or too long.

For small requests (solved exactly) "as few as possible" is proven. For larger ones it is the fewest the search reached in its time; a longer time_limit_ms can place more.

A day that fits is answered exactly as without the option, and no plan has an unplanned field.

Rush hours

With time_of_day at "weekday", how long a drive takes depends on when it starts. Compared with the daily average, a trip on town streets takes about 13% longer between 07:15 and 08:45, about 20% longer between 16:15 and 17:45, a few percent less around midday and a quarter less at night. A trip on country roads or motorways is not changed, and a trip that is partly both is changed in part.

So the same two stops can be 28 minutes apart at noon and 35 minutes apart at five, and a plan that sends a worker across town at five pays for it in drive_seconds and in every arrival after it.

These are estimates for an ordinary working day, not measurements of the day being planned.

Representatives

A front can hold hundreds of plans. representatives names a few to start from:

Several labels may point at the same plan.

Errors

Every error has the same shape:

{ "error": { "code": "no_feasible_plan", "message": "no plan was found that visits every stop while respecting all appointments and shifts" } }
StatuscodeWhen
400invalid_requestMalformed JSON, an unknown field, a missing or duplicate id, a bad time, a window that ends before it starts, a limit exceeded, a point with no road connection, or a point more than 1 km from any road of the loaded map. The message names the stop or worker.
422address_not_resolvedOne or more addresses could not be located well enough. The error lists all of them; see below.
401unauthorizedNo key, or one that is unknown or switched off; see Keys.
422no_feasible_planNo plan visits every stop while keeping all appointments and shifts. For searched requests this means none was found, not that none exists. Never returned with allow_unplanned.
429rate_limitedThe key's customer has used up its requests for this minute. The Retry-After header says how many seconds to wait.
502travel_times_unavailableThe routing engine is down or returned an error.
502geocoder_unavailableThe geocoder is down or returned an error.
503busyAs many plans as the service allows are being computed, and none finished within 15 seconds. Nothing is wrong with the request; send it again. The Retry-After header suggests a wait in seconds.
503unavailableKeys cannot be checked at the moment. Try again shortly.
500internal_errorA bug.

Address errors carry one entry per address that could not be used:

{
  "error": {
    "code": "address_not_resolved",
    "message": "2 address(es) could not be located: stop shop, stop office",
    "addresses": [
      { "owner": "stop shop", "address": "Mariahilfer Straße 9999, 1070 Wien",
        "reason": "house_number_not_found",
        "message": "the map knows Mariahilfer Straße, 1070 Wien but not the house number in \"Mariahilfer Straße 9999, 1070 Wien\"; send coordinates, or set options.address_precision to \"street\" to accept a point on the street" },
      { "owner": "stop office", "address": "Hauptstraße 5",
        "reason": "place_missing",
        "message": "\"Hauptstraße 5\" names no postcode or town, and that street and house number exist in more than one place" }
    ]
  }
}

The reasons are listed under Addresses.

Limits

LimitValue
Stops per request200. A safety limit, not a recommendation: with the default search time the plans are good up to about 50 stops, with 60 s up to about 100, and at 200 stops two minutes give a usable draft
Workers per request50
Search time3 s by default, 120 s at most
Address length200 characters
Distance of a point from the nearest road1 km
Request body2 MB
Plans computed at the same timeOne per CPU core unless configured otherwise; see 503 busy

POST /v1/addresses

Looks addresses up without planning anything, so that a client can show what each one was understood as before a plan is built on it.

{ "addresses": ["Opernring 2, 1010 Wien", "Mariahilfer Straße 9999, 1070 Wien", "Nirgendwogasse 3, 9999 Nirgends"] }
{
  "results": [
    { "address": "Opernring 2, 1010 Wien", "found": true, "precision": "house",
      "matched": "Opernring 2, 1010 Wien", "location": { "lat": 48.2032864, "lon": 16.3691936 } },
    { "address": "Mariahilfer Straße 9999, 1070 Wien", "found": true, "precision": "street",
      "matched": "Mariahilfer Straße, 1070 Wien", "location": { "lat": 48.1967109, "lon": 16.3441586 } },
    { "address": "Nirgendwogasse 3, 9999 Nirgends", "found": false, "reason": "not_found",
      "message": "..." }
  ]
}

One result per address, in the order they were sent. Every address is located as exactly as the map allows, and precision says which it was: house, or street when the house number is not in the map. An address that cannot be located is a result with a reason, not an error of the request; the reasons are those listed under Addresses.

To plan with what was found, send the location of each result as the stop's coordinates. POST /v1/plans then does not look the address up again.

Between 1 and 300 addresses of at most 200 characters are accepted. The server needs a geocoder (GET /health says whether it has one).

POST /v1/geometry

Plans say in which order stops are visited, not which roads are taken. This endpoint returns the line of one route, so that a client can draw the plan it is showing without asking for the lines of all the others.

Send the places of the route in order: the worker's start, the stops, the worker's end. Coordinates come from locations in the plan response.

{ "points": [ { "lat": 48.2082, "lon": 16.3738 }, { "lat": 48.1845, "lon": 16.3122 }, { "lat": 48.2082, "lon": 16.3738 } ] }
{ "source": "osrm", "line": [ [48.207818, 16.373724], [48.207767, 16.373846], [48.207762, 16.373859] ] }
FieldMeaning
source"osrm": the line follows the roads. "straight_line": no routing engine is configured and the line only connects the points.
lineThe line as [lat, lon] pairs, shortened here to its first three. The full answer to this request has 770.

Between 2 and 202 points are accepted. Errors use the same shape and codes as POST /v1/plans.

GET /health

{ "status": "ok", "travel_times": "osrm", "geocoder": "photon" }

travel_times is "osrm" or "straight_line"; geocoder is "photon" or "disabled". Both report how the server is configured, not whether the services behind it are currently reachable.