Docs
Request an API key

v1 endpoints

The older API, in the routing engine's and geocoder's own formats. It still works, but new clients should use /v2.

/docs/legacy/v1.md

New clients should use /v2. These endpoints still work and haven't changed. They use different coordinate order and units from /v2, so a client that talks to both must not share a point-formatting helper.

Rules for v1 calls

  1. Send your key. Programs send X-API-Key on every call except /health. Missing or unknown keys get 401. /isochrone and /spt accept a key only.
  2. point= query parameters are lat,lng. point=10.7202,122.5621 is Iloilo City. This is the opposite of /v2.
  3. POST /route bodies and every response use [lng, lat]. Swap them to lat,lng before you use a returned coordinate in a point= parameter.
  4. profile is car. Any other value returns 400.
  5. distance is in metres and time is in milliseconds. Divide time by 60000 for minutes.
  6. Don't send ch.disable or custom models. They return 403.
  7. POST is for /route only. GET /route and POST to any other endpoint return 403.

The rate limit is 20 requests per second per key, with a burst of 40. Over it, you get 429 with Retry-After.

POST /route

bash
curl -s -X POST -H 'Content-Type: application/json' -H "X-API-Key: $QUADRUPER_KEY" \
  -d '{"points":[[122.5621,10.7202],[122.5644,10.6969]],"profile":"car","points_encoded":false,"instructions":true,"locale":"en"}' \
  https://quadruper.com/route
Field Required Description
points Yes 2 or more [lng, lat] pairs, in travel order. Stops aren't reordered. Keep consecutive points within 1000 km.
profile Yes car
points_encoded No false returns GeoJSON geometry. The default is an encoded polyline.
calc_points No false leaves out the geometry.
instructions No true (default) returns turn-by-turn steps.
locale No Language of the instruction text.
details No Array of per-segment attributes such as road_class, street_name, max_speed or road_environment.
point_hints No Array, one entry per point. Helps snap to a named street.
snap_preventions No Array. Stops a point snapping onto a road type. The default already avoids tunnel, bridge and ferry.

The body is limited to 32 KB. For distance and time only, send "calc_points":false,"instructions":false.

The fields you usually need are in paths[0]:

Field Meaning
distance Total metres
time Total milliseconds
bbox [minLng, minLat, maxLng, maxLat] of the route
points GeoJSON LineString, coordinates [lng, lat]
instructions[] Steps with text, distance, time, street_name, sign and interval (an index range into points)
details.<name> Lists of [fromIndex, toIndex, value] over points

Common sign values: 0 continue, -2 left, 2 right, -1 and 1 slight left and right, -3 and 3 sharp left and right, 7 keep right, -7 keep left, 6 roundabout, 4 arrive.

v1 has no matrix. Use POST /v2/matrix.

GET /nearest

bash
curl -s -H "X-API-Key: $QUADRUPER_KEY" 'https://quadruper.com/nearest?point=10.7202,122.5621'

Returns {"type": "Point", "coordinates": [lng, lat], "distance": 2.93}. distance is how far in metres the input was from the road.

GET /info

bash
curl -s -H "X-API-Key: $QUADRUPER_KEY" https://quadruper.com/info

Useful fields are bbox, profiles, data_date and import_date.

GET /health

bash
curl -s https://quadruper.com/health

Returns OK when the service is up. It needs no key.

GET /geocode/...

These return GeoJSON FeatureCollections. Each feature's coordinates are [lng, lat], and its properties include name, type, osm_key, osm_value and country.

bash
# Forward search
curl -s -H "X-API-Key: $QUADRUPER_KEY" 'https://quadruper.com/geocode/api?q=Iloilo&limit=1'

# Reverse lookup
curl -s -H "X-API-Key: $QUADRUPER_KEY" 'https://quadruper.com/geocode/reverse?lat=10.7202&lon=122.5621'

# Structured search
curl -s -H "X-API-Key: $QUADRUPER_KEY" 'https://quadruper.com/geocode/structured?countrycode=PH&city=Davao'

GET /isochrone

Key only, and expensive. Keep time_limit small, such as 300 to 900 seconds.

bash
curl -s -H "X-API-Key: $QUADRUPER_KEY" \
  'https://quadruper.com/isochrone?point=10.7202,122.5621&profile=car&time_limit=300'

buckets=3 splits the area into rings. reverse_flow=true gives the area that can reach the point instead. The response is {"polygons": [GeoJSON Feature, ...]}.

GET /spt

Key only, and expensive. Returns a CSV table of every node reachable within the time limit. time is in milliseconds and distance in metres.

bash
curl -s -H "X-API-Key: $QUADRUPER_KEY" \
  'https://quadruper.com/spt?point=10.7202,122.5621&profile=car&time_limit=60&columns=longitude,latitude,time,distance'

GET /mvt/{z}/{x}/{y}.mvt

Mapbox Vector Tiles (application/x-protobuf) of the routable road graph, for map clients that want to draw the network. Tiles outside the Philippines are empty.

v1 errors

Errors return a JSON body with a human-readable message and a hints[] list. hints[].point_index tells you which point caused the problem.

Status Example message What to do
400 Point 1 is out of bounds Check the point and that it uses lat,lng order.
400 The requested profile 'foot' does not exist Use profile=car.
400 Cannot find point 0 The point is too far from a drivable road. Move it, or call /nearest first.
400 Connection between locations not found No road link exists. Tell the user, and don't retry.
429 Monthly data cap reached. Contact the operator to raise it. Don't retry. See Known limits.
429 Rate limit exceeded. Slow down and retry. Wait and retry with backoff.
5xx Check /health, then retry with backoff a few times at most.