{ "openapi": "3.1.0", "info": { "title": "Quadruper API", "version": "2.0", "description": "Routing and geocoding over HTTPS. Guides and rules: https://quadruper.com/docs/" }, "servers": [ { "url": "https://quadruper.com" } ], "security": [ { "ApiKey": [] } ], "paths": { "/v2/route": { "post": { "operationId": "route", "summary": "Get a route, distance and ETA between 2 to 10 points", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteResponse" } } } }, "default": { "description": "Error. Branch on `code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteRequest" } } } } } }, "/v2/matrix": { "post": { "operationId": "matrix", "summary": "Get durations and distances between many origins and destinations", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixResponse" } } } }, "default": { "description": "Error. Branch on `code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixRequest" } } } } } }, "/v2/nearest": { "get": { "operationId": "nearest", "summary": "Snap a point to the nearest drivable road", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NearestResponse" } } } }, "default": { "description": "Error. Branch on `code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "point", "in": "query", "required": true, "schema": { "type": "string", "description": "Coordinate as lng,lat, for example 122.5621,10.7202" } }, { "name": "profile", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Common/$defs/profile" } } ] } }, "/v2/isochrone": { "get": { "operationId": "isochrone", "summary": "Get the areas reachable within 1 to 3 travel times", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IsochroneResponse" } } } }, "default": { "description": "Error. Branch on `code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "point", "in": "query", "required": true, "schema": { "type": "string", "description": "Coordinate as lng,lat, for example 122.5621,10.7202" } }, { "name": "profile", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Common/$defs/profile" } }, { "name": "time_s", "in": "query", "required": true, "schema": { "type": "string", "description": "1 to 3 comma-separated values, each a multiple of 60 from 60 to 1800, strictly ascending" } } ] } }, "/v2/geocode": { "get": { "operationId": "geocode", "summary": "Turn a place name or address into coordinates", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeResponse" } } } }, "default": { "description": "Error. Branch on `code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "street", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "house_number", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 20 } }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "county", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "postcode", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 20 } }, { "name": "country_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z]{2}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10 } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z]{2}$" } }, { "name": "near", "in": "query", "required": false, "schema": { "type": "string", "description": "Rank results near this point, as lng,lat" } }, { "name": "near_text", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "bbox", "in": "query", "required": false, "schema": { "type": "string", "description": "Only return results inside this box, as minLng,minLat,maxLng,maxLat" } } ] } }, "/v2/reverse": { "get": { "operationId": "reverse", "summary": "Turn coordinates into the nearest place", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeResponse" } } } }, "default": { "description": "Error. Branch on `code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "point", "in": "query", "required": true, "schema": { "type": "string", "description": "Coordinate as lng,lat, for example 122.5621,10.7202" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z]{2}$" } } ] } }, "/v2/info": { "get": { "operationId": "info", "summary": "Read coverage, profiles, data date and capabilities", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfoResponse" } } } }, "default": { "description": "Error. Branch on `code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "Common": { "title": "GeoApiCommon", "description": "Shared definitions for the geo-api /v2 contract.", "$defs": { "lnglat": { "title": "LngLat", "type": "array", "prefixItems": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "number", "minimum": -90, "maximum": 90 } ], "minItems": 2, "maxItems": 2, "items": false }, "bbox": { "title": "BBox", "description": "[minLng, minLat, maxLng, maxLat]", "type": "array", "prefixItems": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "number", "minimum": -90, "maximum": 90 } ], "minItems": 4, "maxItems": 4, "items": false }, "profile": { "title": "Profile", "description": "Any short name is accepted here; geo-api answers unsupported_profile for names the deployment does not offer.", "type": "string", "pattern": "^[a-z][a-z_]{0,31}$" }, "nullableString": { "title": "NullableString", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "attribution": { "title": "Attribution", "type": "array", "minItems": 1, "items": { "title": "AttributionEntry", "type": "object", "properties": { "source": { "enum": [ "osm", "local" ] }, "text": { "type": "string", "minLength": 1 }, "license": { "type": "string", "minLength": 1 } }, "required": [ "source", "text", "license" ], "additionalProperties": false } }, "conditions": { "title": "Conditions", "type": "object", "properties": { "assessed": { "type": "boolean", "const": false }, "reason": { "enum": [ "not_configured" ] } }, "required": [ "assessed", "reason" ], "additionalProperties": false }, "address": { "title": "Address", "type": "object", "properties": { "house_number": { "type": "string" }, "street": { "type": "string" }, "locality": { "type": "string" }, "district": { "type": "string" }, "city": { "type": "string" }, "county": { "type": "string" }, "state": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" }, "country_code": { "type": "string", "pattern": "^[a-z]{2}$" } }, "additionalProperties": false }, "place": { "title": "Place", "type": "object", "properties": { "source": { "enum": [ "osm", "local" ] }, "id": { "oneOf": [ { "type": "string", "pattern": "^[A-Za-z0-9/_-]{1,80}$" }, { "type": "null" } ] }, "name": { "$ref": "#/components/schemas/Common/$defs/nullableString" }, "label": { "type": "string", "minLength": 1 }, "location": { "$ref": "#/components/schemas/Common/$defs/lnglat" }, "category": { "$ref": "#/components/schemas/Common/$defs/nullableString" }, "type": { "$ref": "#/components/schemas/Common/$defs/nullableString" }, "address": { "$ref": "#/components/schemas/Common/$defs/address" } }, "required": [ "source", "id", "name", "label", "location", "category", "type", "address" ], "additionalProperties": false }, "ring": { "title": "LinearRing", "type": "array", "minItems": 4, "items": { "$ref": "#/components/schemas/Common/$defs/lnglat" } }, "polygonal": { "title": "Polygonal", "oneOf": [ { "title": "Polygon", "type": "object", "properties": { "type": { "const": "Polygon" }, "coordinates": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Common/$defs/ring" } } }, "required": [ "type", "coordinates" ], "additionalProperties": false }, { "title": "MultiPolygon", "type": "object", "properties": { "type": { "const": "MultiPolygon" }, "coordinates": { "type": "array", "minItems": 1, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Common/$defs/ring" } } } }, "required": [ "type", "coordinates" ], "additionalProperties": false } ] }, "step": { "title": "Step", "type": "object", "properties": { "type": { "enum": [ "depart", "arrive", "waypoint", "continue", "turn_left", "turn_right", "turn_slight_left", "turn_slight_right", "turn_sharp_left", "turn_sharp_right", "keep_left", "keep_right", "u_turn", "roundabout" ] }, "instruction": { "type": "string" }, "name": { "$ref": "#/components/schemas/Common/$defs/nullableString" }, "distance_m": { "type": "number", "minimum": 0 }, "duration_s": { "type": "number", "minimum": 0 }, "location": { "$ref": "#/components/schemas/Common/$defs/lnglat" }, "geometry_index": { "type": "array", "prefixItems": [ { "type": "integer", "minimum": 0 }, { "type": "integer", "minimum": 0 } ], "minItems": 2, "maxItems": 2, "items": false }, "exit": { "type": "integer", "minimum": 1 } }, "required": [ "type", "instruction", "name", "distance_m", "duration_s", "location", "geometry_index" ], "additionalProperties": false, "if": { "type": "object", "properties": { "type": { "const": "roundabout" } }, "required": [ "type" ] }, "then": { "required": [ "exit" ] }, "else": { "not": { "required": [ "exit" ] } } }, "leg": { "title": "Leg", "type": "object", "properties": { "distance_m": { "type": "number", "minimum": 0 }, "duration_s": { "type": "number", "minimum": 0 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/Common/$defs/step" } } }, "required": [ "distance_m", "duration_s", "steps" ], "additionalProperties": false }, "waypoint": { "title": "Waypoint", "type": "object", "properties": { "location": { "$ref": "#/components/schemas/Common/$defs/lnglat" }, "snapped_distance_m": { "type": "number", "minimum": 0 } }, "required": [ "location", "snapped_distance_m" ], "additionalProperties": false }, "matrixPoint": { "title": "MatrixPoint", "type": "object", "properties": { "location": { "$ref": "#/components/schemas/Common/$defs/lnglat" }, "snapped": { "type": "boolean" } }, "required": [ "location", "snapped" ], "additionalProperties": false }, "matrixRow": { "title": "MatrixRow", "type": "array", "minItems": 1, "maxItems": 25, "items": { "oneOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } } } }, "Error": { "title": "ErrorBody", "description": "Every /v2 error body, from geo-api or from nginx (spec section 3.9).", "type": "object", "properties": { "code": { "enum": [ "invalid_request", "unsupported_profile", "too_many_points", "too_many_cells", "unauthorized", "forbidden", "not_found", "payload_too_large", "unsupported_media_type", "point_not_snapped", "out_of_coverage", "no_route", "reference_not_found", "rate_limited", "internal_error", "capability_unavailable", "engine_unavailable", "unavailable", "engine_timeout", "trial_exhausted", "trial_unavailable", "data_cap_exceeded" ] }, "message": { "type": "string", "minLength": 1 }, "details": { "type": "object" } }, "required": [ "code", "message" ], "additionalProperties": false }, "GeocodeQuery": { "title": "GeocodeQuery", "description": "GET /v2/geocode query, parsed. Either q or at least one structured field; never near with near_text.", "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 200 }, "street": { "type": "string", "minLength": 1, "maxLength": 200 }, "house_number": { "type": "string", "minLength": 1, "maxLength": 20 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "county": { "type": "string", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "minLength": 1, "maxLength": 100 }, "postcode": { "type": "string", "minLength": 1, "maxLength": 20 }, "country_code": { "type": "string", "pattern": "^[a-z]{2}$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 10 }, "lang": { "type": "string", "pattern": "^[a-z]{2}$" }, "near": { "$ref": "#/components/schemas/Common/$defs/lnglat" }, "near_text": { "type": "string", "minLength": 1, "maxLength": 200 }, "bbox": { "$ref": "#/components/schemas/Common/$defs/bbox" } }, "additionalProperties": false, "allOf": [ { "not": { "required": [ "near", "near_text" ] } }, { "oneOf": [ { "required": [ "q" ], "not": { "anyOf": [ { "required": [ "street" ] }, { "required": [ "house_number" ] }, { "required": [ "city" ] }, { "required": [ "county" ] }, { "required": [ "state" ] }, { "required": [ "postcode" ] }, { "required": [ "country_code" ] } ] } }, { "not": { "required": [ "q" ] }, "anyOf": [ { "required": [ "street" ] }, { "required": [ "house_number" ] }, { "required": [ "city" ] }, { "required": [ "county" ] }, { "required": [ "state" ] }, { "required": [ "postcode" ] }, { "required": [ "country_code" ] } ] } ] } ] }, "GeocodeResponse": { "title": "GeocodeResponse", "description": "GET /v2/geocode and GET /v2/reverse 200 body. reference is present only when near_text was used.", "type": "object", "properties": { "results": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/Common/$defs/place" } }, "reference": { "title": "Reference", "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "location": { "$ref": "#/components/schemas/Common/$defs/lnglat" } }, "required": [ "label", "location" ], "additionalProperties": false }, "attribution": { "$ref": "#/components/schemas/Common/$defs/attribution" } }, "required": [ "results", "attribution" ], "additionalProperties": false }, "InfoResponse": { "title": "InfoResponse", "description": "GET /v2/info 200 body. A capability is listed only when its endpoint works.", "type": "object", "properties": { "contract_version": { "type": "string", "pattern": "^2\\.[0-9]+$" }, "coverage": { "type": "object", "properties": { "bbox": { "$ref": "#/components/schemas/Common/$defs/bbox" } }, "required": [ "bbox" ], "additionalProperties": false }, "routing": { "type": "object", "properties": { "engine": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 }, "profiles": { "type": "array", "minItems": 1, "items": { "title": "ProfileInfo", "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Common/$defs/profile" }, "approximate": { "type": "boolean" } }, "required": [ "name", "approximate" ], "additionalProperties": false } } }, "required": [ "engine", "version", "profiles" ], "additionalProperties": false }, "geocoding": { "type": "object", "properties": { "engine": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } }, "required": [ "engine", "version" ], "additionalProperties": false }, "sources": { "type": "array", "minItems": 1, "items": { "title": "SourceInfo", "type": "object", "properties": { "source": { "enum": [ "osm", "local" ] }, "data_date": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, { "type": "null" } ] } }, "required": [ "source", "data_date" ], "additionalProperties": false } }, "capabilities": { "title": "Capabilities", "type": "object", "properties": { "route": { "type": "object", "properties": { "max_points": { "const": 10 }, "steps": { "type": "boolean" } }, "required": [ "max_points", "steps" ], "additionalProperties": false }, "nearest": { "type": "object", "additionalProperties": false }, "isochrone": { "type": "object", "properties": { "max_values": { "const": 3 }, "max_time_s": { "const": 1800 }, "step_s": { "const": 60 } }, "required": [ "max_values", "max_time_s", "step_s" ], "additionalProperties": false }, "matrix": { "type": "object", "properties": { "max_cells": { "const": 25 } }, "required": [ "max_cells" ], "additionalProperties": false }, "geocode": { "type": "object", "properties": { "max_limit": { "const": 10 }, "structured": { "type": "boolean" }, "near": { "type": "boolean" }, "near_text": { "type": "boolean" }, "bbox": { "type": "boolean" } }, "required": [ "max_limit", "structured", "near", "near_text", "bbox" ], "additionalProperties": false }, "reverse": { "type": "object", "additionalProperties": false } }, "required": [ "route", "geocode", "reverse" ], "additionalProperties": false }, "attribution": { "$ref": "#/components/schemas/Common/$defs/attribution" } }, "required": [ "contract_version", "coverage", "routing", "geocoding", "sources", "capabilities", "attribution" ], "additionalProperties": false }, "IsochroneQuery": { "title": "IsochroneQuery", "description": "GET /v2/isochrone query, parsed. geo-api also requires time_s to be strictly ascending.", "type": "object", "properties": { "point": { "$ref": "#/components/schemas/Common/$defs/lnglat" }, "profile": { "$ref": "#/components/schemas/Common/$defs/profile" }, "time_s": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "integer", "minimum": 60, "maximum": 1800, "multipleOf": 60 } } }, "required": [ "point", "time_s" ], "additionalProperties": false }, "IsochroneResponse": { "title": "IsochroneResponse", "description": "GET /v2/isochrone 200 body: a GeoJSON FeatureCollection with conditions and attribution as foreign members.", "type": "object", "properties": { "type": { "const": "FeatureCollection" }, "features": { "type": "array", "minItems": 1, "items": { "title": "IsochroneFeature", "type": "object", "properties": { "type": { "const": "Feature" }, "geometry": { "$ref": "#/components/schemas/Common/$defs/polygonal" }, "properties": { "type": "object", "properties": { "time_s": { "type": "integer", "minimum": 60, "maximum": 1800 } }, "required": [ "time_s" ], "additionalProperties": false } }, "required": [ "type", "geometry", "properties" ], "additionalProperties": false } }, "conditions": { "$ref": "#/components/schemas/Common/$defs/conditions" }, "attribution": { "$ref": "#/components/schemas/Common/$defs/attribution" } }, "required": [ "type", "features", "conditions", "attribution" ], "additionalProperties": false }, "MatrixRequest": { "title": "MatrixRequest", "description": "POST /v2/matrix body. sources x destinations is at most 25; geo-api checks the product.", "type": "object", "properties": { "sources": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "$ref": "#/components/schemas/Common/$defs/lnglat" } }, "destinations": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "$ref": "#/components/schemas/Common/$defs/lnglat" } }, "profile": { "$ref": "#/components/schemas/Common/$defs/profile" } }, "required": [ "sources", "destinations" ], "additionalProperties": false }, "MatrixResponse": { "title": "MatrixResponse", "description": "POST /v2/matrix 200 body. Rows follow sources, columns follow destinations; null = no route or unsnapped point.", "type": "object", "properties": { "sources": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "$ref": "#/components/schemas/Common/$defs/matrixPoint" } }, "destinations": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "$ref": "#/components/schemas/Common/$defs/matrixPoint" } }, "durations_s": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "$ref": "#/components/schemas/Common/$defs/matrixRow" } }, "distances_m": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "$ref": "#/components/schemas/Common/$defs/matrixRow" } }, "conditions": { "$ref": "#/components/schemas/Common/$defs/conditions" }, "attribution": { "$ref": "#/components/schemas/Common/$defs/attribution" } }, "required": [ "sources", "destinations", "durations_s", "distances_m", "conditions", "attribution" ], "additionalProperties": false }, "NearestQuery": { "title": "NearestQuery", "description": "GET /v2/nearest query, after geo-api parses point=lng,lat into a pair.", "type": "object", "properties": { "point": { "$ref": "#/components/schemas/Common/$defs/lnglat" }, "profile": { "$ref": "#/components/schemas/Common/$defs/profile" } }, "required": [ "point" ], "additionalProperties": false }, "NearestResponse": { "title": "NearestResponse", "description": "GET /v2/nearest 200 body.", "type": "object", "properties": { "location": { "$ref": "#/components/schemas/Common/$defs/lnglat" }, "distance_m": { "type": "number", "minimum": 0 }, "attribution": { "$ref": "#/components/schemas/Common/$defs/attribution" } }, "required": [ "location", "distance_m", "attribution" ], "additionalProperties": false }, "ReverseQuery": { "title": "ReverseQuery", "description": "GET /v2/reverse query, parsed.", "type": "object", "properties": { "point": { "$ref": "#/components/schemas/Common/$defs/lnglat" }, "lang": { "type": "string", "pattern": "^[a-z]{2}$" } }, "required": [ "point" ], "additionalProperties": false }, "RouteRequest": { "title": "RouteRequest", "description": "POST /v2/route body.", "type": "object", "properties": { "points": { "type": "array", "minItems": 2, "maxItems": 10, "items": { "$ref": "#/components/schemas/Common/$defs/lnglat" } }, "profile": { "$ref": "#/components/schemas/Common/$defs/profile" }, "steps": { "type": "boolean" } }, "required": [ "points" ], "additionalProperties": false }, "RouteResponse": { "title": "RouteResponse", "description": "POST /v2/route 200 body.", "type": "object", "properties": { "routes": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "title": "Route", "type": "object", "properties": { "distance_m": { "type": "number", "minimum": 0 }, "duration_s": { "type": "number", "minimum": 0 }, "geometry": { "title": "LineString", "type": "object", "properties": { "type": { "const": "LineString" }, "coordinates": { "type": "array", "minItems": 2, "items": { "$ref": "#/components/schemas/Common/$defs/lnglat" } } }, "required": [ "type", "coordinates" ], "additionalProperties": false }, "waypoints": { "type": "array", "minItems": 2, "maxItems": 10, "items": { "$ref": "#/components/schemas/Common/$defs/waypoint" } }, "legs": { "type": "array", "minItems": 1, "maxItems": 9, "items": { "$ref": "#/components/schemas/Common/$defs/leg" } } }, "required": [ "distance_m", "duration_s", "geometry", "waypoints", "legs" ], "additionalProperties": false } }, "conditions": { "$ref": "#/components/schemas/Common/$defs/conditions" }, "attribution": { "$ref": "#/components/schemas/Common/$defs/attribution" } }, "required": [ "routes", "conditions", "attribution" ], "additionalProperties": false } } } }