{ "openapi": "3.1.0", "info": { "title": "Mapora API", "version": "3.0.0", "description": "API geográfica de Mapora. Requiere API key. Cada petición geográfica autenticada admitida consume una unidad, también si responde desde caché o devuelve un error. Free: 1.000/mes; Launch: 25.000/mes; Scale: sin cuota mensual. Se aplican límites por minuto. Búsqueda y consulta inversa con Photon/OpenStreetMap. Autocompletado, búsqueda estructurada mundial, lugares cercanos, lotes (10 direcciones), cobertura GeoJSON y rutas/matrices (Latinoamérica inicialmente, ampliación mundial pendiente). Cada llamada HTTP admitida consume una petición; no hay tráfico en tiempo real.", "license": { "name": "Private application; geographic data © OpenStreetMap contributors (ODbL)", "url": "https://www.openstreetmap.org/copyright" } }, "servers": [ { "url": "https://maps-api.nexode.app" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "paths": { "/health": { "get": { "summary": "Local process health (does not test providers)", "responses": { "200": { "description": "Healthy" }, "401": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Account suspended or missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Monthly quota or per-minute rate exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "security": [], "description": "" } }, "/v1/search": { "get": { "summary": "Search addresses, streets, districts and places", "description": "Worldwide place search plus an offline Peru street index when Peru or local context is selected. Street references do not verify a requested house number; inspect quality and match.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Text, 2 to 200 characters", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results, 1 to 20 (default 8)", "schema": { "type": "integer" } }, { "name": "countrycodes", "in": "query", "required": false, "description": "Comma-separated country codes: pe,co,ec", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "required": false, "description": "Latitude of preferred search area", "schema": { "type": "number" } }, { "name": "lng", "in": "query", "required": false, "description": "Longitude of preferred search area; lon is also accepted", "schema": { "type": "number" } }, { "name": "bbox", "in": "query", "required": false, "description": "Restrict to minLng,minLat,maxLng,maxLat", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "description": "es/local (local names), en, de or fr", "schema": { "type": "string" } }, { "name": "city", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "Normalized administrative-name filter. Use countrycodes=PE for the supplementary offline Peru street index; bbox remains a rectangular geographic constraint." }, { "name": "district", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "Normalized administrative-name filter. Use countrycodes=PE for the supplementary offline Peru street index; bbox remains a rectangular geographic constraint." }, { "name": "state", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "Normalized administrative-name filter. Use countrycodes=PE for the supplementary offline Peru street index; bbox remains a rectangular geographic constraint." } ], "responses": { "200": { "description": "Search candidates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "Google Maps link could not be resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "502": { "description": "Geocoding provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Service busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "504": { "description": "Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Account suspended or missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Monthly quota or per-minute rate exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } } }, "/v1/reverse": { "get": { "summary": "Reverse geocode coordinates", "description": "Top-level coordinates remain the requested point. matchedLatitude/matchedLongitude identify the nearby OSM feature. The nearest feature may be a POI, not an exact street address.", "parameters": [ { "name": "lat", "in": "query", "required": true, "description": "Latitude", "schema": { "type": "number" } }, { "name": "lng", "in": "query", "required": true, "description": "Longitude; lon is also accepted", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "Google Maps link could not be resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "502": { "description": "Geocoding provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Service busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "504": { "description": "Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Account suspended or missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Monthly quota or per-minute rate exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } } }, "/v1/resolve": { "post": { "summary": "Resolve a Google Maps link", "description": "Keeps the exact Google pin and selected venue name. includeAddress defaults to true. If address lookup fails, coordinates remain available and addressStatus is unavailable. includeAddress=false skips reverse geocoding. cached refers to the link/pin cache. resolved_url retains the expanded URL. This does not call Google Places.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "maxLength": 4096 }, "includeAddress": { "type": "boolean", "default": true } } }, "example": { "url": "https://www.google.com/maps/place/Plaza+Mayor/@-12.0453,-77.0309,17z", "includeAddress": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "Google Maps link could not be resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "502": { "description": "Geocoding provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Service busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "504": { "description": "Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Account suspended or missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Monthly quota or per-minute rate exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } }, "get": { "summary": "Resolve via query parameters", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Google Maps HTTPS link", "schema": { "type": "string" } }, { "name": "includeAddress", "in": "query", "required": false, "description": "Whether to reverse geocode the pin", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "Google Maps link could not be resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "502": { "description": "Geocoding provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Service busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "504": { "description": "Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Account suspended or missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Monthly quota or per-minute rate exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "description": "" } }, "/v1/maps": { "post": { "summary": "Create an interactive, embeddable map", "description": "Requires maps scope. Consumes one admitted API request. Returns an opaque public view capability, never an API key. Opening/panning/zooming the viewer does not consume additional Mapora requests. Links expire (7 days by default, 30 maximum) and become unavailable when the issuing key is revoked or the account disabled. Public OpenStreetMap raster tiles are loaded directly by the browser, with no availability guarantee.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "anyOf": [ { "required": [ "center" ] }, { "required": [ "markers" ] } ], "properties": { "title": { "type": "string", "maxLength": 160 }, "center": { "$ref": "#/components/schemas/MapPoint" }, "markers": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "$ref": "#/components/schemas/MapPoint" } }, "zoom": { "type": "integer", "minimum": 1, "maximum": 19, "default": 14 }, "expiresIn": { "type": "integer", "minimum": 60, "maximum": 2592000, "default": 604800 }, "theme": { "enum": [ "light", "dark", "grayscale" ] }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "shapes": { "type": "array", "items": { "$ref": "#/components/schemas/Polygon" }, "minItems": 0, "maxItems": 10 }, "route": { "$ref": "#/components/schemas/LineString" } } } } } }, "responses": { "201": { "description": "Map created", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "embedHtml": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "map": { "type": "object" }, "usage": { "type": "string" } } } } } }, "400": { "description": "Invalid coordinates, markers, zoom or lifetime", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "maps scope required or suspended account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Quota or rate exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Storage or quota unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } } }, "/v1/maps/view/{token}": { "get": { "summary": "Read the map described by a view capability", "security": [], "description": "Public only to holders of the opaque map token. Does not grant geocoding, account access or key access. Does not consume quota. No-store responses preserve revocation and expiry checks.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Map specification and expiry" }, "404": { "description": "Invalid, expired, revoked or suspended map", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } } }, "/v1/autocomplete": { "get": { "summary": "Address autocomplete (search scope)", "description": "Worldwide place search plus an offline Peru street index when Peru or local context is selected. Street references do not verify a requested house number; inspect quality and match.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Text, 2 to 200 characters", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results, 1 to 20 (default 8)", "schema": { "type": "integer" } }, { "name": "countrycodes", "in": "query", "required": false, "description": "Comma-separated country codes: pe,co,ec", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "required": false, "description": "Latitude of preferred search area", "schema": { "type": "number" } }, { "name": "lng", "in": "query", "required": false, "description": "Longitude of preferred search area; lon is also accepted", "schema": { "type": "number" } }, { "name": "bbox", "in": "query", "required": false, "description": "Restrict to minLng,minLat,maxLng,maxLat", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "description": "es/local (local names), en, de or fr", "schema": { "type": "string" } }, { "name": "city", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "Normalized administrative-name filter. Use countrycodes=PE for the supplementary offline Peru street index; bbox remains a rectangular geographic constraint." }, { "name": "district", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "Normalized administrative-name filter. Use countrycodes=PE for the supplementary offline Peru street index; bbox remains a rectangular geographic constraint." }, { "name": "state", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "Normalized administrative-name filter. Use countrycodes=PE for the supplementary offline Peru street index; bbox remains a rectangular geographic constraint." } ], "responses": { "200": { "description": "Search candidates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "Google Maps link could not be resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "502": { "description": "Geocoding provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Service busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "504": { "description": "Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Account suspended or missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Monthly quota or per-minute rate exceeded; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } } }, "/v1/geocode": { "get": { "summary": "Structured address search", "description": "Required scope: search. One admitted HTTP request consumes one plan request.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Scope/origin/account denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Quota/rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "502": { "description": "Geographic engine unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Service busy/unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum results, 1 to 20 (default 8)", "schema": { "type": "integer" } }, { "name": "countrycodes", "in": "query", "required": false, "description": "Comma-separated country codes: pe,co,ec", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "description": "es/local (local names), en, de or fr", "schema": { "type": "string" } }, { "in": "query", "name": "street", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "in": "query", "name": "housenumber", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "in": "query", "name": "city", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "in": "query", "name": "district", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "in": "query", "name": "state", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "in": "query", "name": "county", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "in": "query", "name": "postcode", "required": false, "schema": { "type": "string", "maxLength": 200 } } ] } }, "/v1/nearby": { "get": { "summary": "Find nearby indexed points of interest", "description": "Required scope: nearby. One admitted HTTP request consumes one plan request.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NearbyResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Scope/origin/account denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Quota/rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "502": { "description": "Geographic engine unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Service busy/unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "parameters": [ { "in": "query", "name": "lat", "required": true, "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "in": "query", "name": "lng", "required": true, "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "in": "query", "name": "category", "required": true, "schema": { "enum": [ "pharmacy", "restaurant", "hospital", "fuel", "supermarket", "hotel", "bank", "parking", "cafe" ] } }, { "in": "query", "name": "radius", "required": false, "schema": { "type": "number", "minimum": 50, "maximum": 50000, "default": 5000 } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 8 } } ] } }, "/v1/batch": { "post": { "summary": "Geocode up to10 addresses, ordered per-item outcomes", "description": "Required scope: batch. One admitted HTTP request consumes one plan request.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Scope/origin/account denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Quota/rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "502": { "description": "Geographic engine unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Service busy/unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "maxLength": 80 }, "query": { "type": "string", "minLength": 2, "maxLength": 200 }, "countrycodes": { "type": "string", "description": "Comma-separated ISO alpha2 codes, max10." } }, "required": [ "query" ] }, "minItems": 1, "maxItems": 10 } }, "required": [ "items" ] } } } } } }, "/v1/coverage": { "post": { "summary": "Check inline delivery zones", "description": "Required scope: coverage. One admitted HTTP request consumes one plan request.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Scope/origin/account denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Quota/rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "502": { "description": "Geographic engine unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Service busy/unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "point": { "$ref": "#/components/schemas/Point" }, "zones": { "type": "array", "items": { "$ref": "#/components/schemas/Zone" }, "minItems": 1, "maxItems": 20 } }, "required": [ "point", "zones" ] } } } } } }, "/v1/coverage/check": { "post": { "summary": "Check saved zones owned by this key account", "description": "Required scope: coverage. One admitted HTTP request consumes one plan request.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Scope/origin/account denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Quota/rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "502": { "description": "Geographic engine unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Service busy/unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "point": { "$ref": "#/components/schemas/Point" }, "zoneIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20 } }, "required": [ "point", "zoneIds" ] } } } } } }, "/v1/routes": { "post": { "summary": "Compute street route, GeoJSON and instructions", "description": "Required scope: routing. One admitted HTTP request consumes one plan request.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Scope/origin/account denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Quota/rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "502": { "description": "Geographic engine unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Service busy/unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "No accessible road/path connection in available routing data; no straight-line substitute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Point" }, "minItems": 2, "maxItems": 10 }, "profile": { "enum": [ "driving", "walking", "cycling" ], "default": "driving" } }, "required": [ "locations" ] } } } } } }, "/v1/matrix": { "post": { "summary": "Travel times and distances for up to10x10 pairs", "description": "Required scope: routing. One admitted HTTP request consumes one plan request.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "401": { "description": "Missing or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "403": { "description": "Scope/origin/account denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "429": { "description": "Quota/rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "502": { "description": "Geographic engine unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "503": { "description": "Service busy/unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } }, "422": { "description": "No accessible road/path connection in available routing data; no straight-line substitute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Point" }, "minItems": 1, "maxItems": 10 }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Point" }, "minItems": 1, "maxItems": 10 }, "profile": { "enum": [ "driving", "walking", "cycling" ], "default": "driving" } }, "required": [ "sources", "targets" ] } } } } } }, "/status": { "get": { "summary": "Cached live dependency status (not availability history)", "security": [], "responses": { "200": { "description": "Status, checkedAt, components and request limits" }, "503": { "description": "Unable to check status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIError" } } } } } } } }, "components": { "schemas": { "Location": { "type": "object", "properties": { "id": { "type": "string" }, "placeName": { "type": "string" }, "address": { "type": "string" }, "streetAddress": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "street": { "type": "string" }, "houseNumber": { "type": "string" }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "countryCode": { "type": "string" }, "postcode": { "type": "string" }, "googleMapsLink": { "type": "string" }, "source": { "type": "string" }, "attribution": { "type": "string" }, "resolved_url": { "type": "string" }, "addressStatus": { "type": "string" }, "matchedPlaceName": { "type": "string" }, "matchedLatitude": { "type": "number" }, "matchedLongitude": { "type": "number" }, "cached": { "type": "boolean" }, "tookMs": { "type": "number" }, "quality": { "$ref": "#/components/schemas/AddressQuality" }, "distanceMeters": { "type": "number", "description": "Straight-line meters from nearby query center." }, "county": { "type": "string" }, "match": { "$ref": "#/components/schemas/StreetMatch" } } }, "MapPoint": { "type": "object", "required": [ "latitude", "longitude" ], "additionalProperties": false, "properties": { "latitude": { "type": "number", "minimum": -85.05112878, "maximum": 85.05112878 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "label": { "type": "string", "maxLength": 160 } } }, "Point": { "type": "object", "additionalProperties": false, "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ] }, "AddressQuality": { "type": "object", "additionalProperties": false, "properties": { "precision": { "type": "string", "description": "Feature type, street or address; source completeness, not accuracy certification." }, "missingFields": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 4 }, "verified": { "const": false } }, "required": [ "precision", "missingFields", "verified" ] }, "Polygon": { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "Polygon" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "minItems": 4, "maxItems": 200 }, "minItems": 1, "maxItems": 5 } }, "required": [ "type", "coordinates" ], "description": "GeoJSON [longitude,latitude]. Closed non-crossing rings, max200 total vertices; exterior + up to4 holes; no antimeridian crossing." }, "Zone": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "maxLength": 80 }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "geometry": { "$ref": "#/components/schemas/Polygon" }, "feeCents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "name", "geometry", "feeCents", "currency" ] }, "LineString": { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "LineString" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "minItems": 2, "maxItems": 10000 } }, "required": [ "type", "coordinates" ] }, "APIError": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" } }, "required": [ "code", "error" ] }, "SearchResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "count": { "type": "integer", "minimum": 0 }, "attribution": { "type": "string" }, "cached": { "type": "boolean" }, "tookMs": { "type": "number", "minimum": 0 } }, "required": [ "results", "count", "attribution" ] }, "NearbyResponse": { "allOf": [ { "$ref": "#/components/schemas/SearchResponse" }, { "type": "object", "properties": { "radiusMeters": { "type": "number", "minimum": 0 }, "distanceType": { "const": "straight_line" }, "category": { "type": "string", "enum": [ "pharmacy", "restaurant", "hospital", "fuel", "supermarket", "hotel", "bank", "parking", "cafe" ] } }, "required": [ "radiusMeters", "distanceType", "category" ] } ] }, "RouteGeometry": { "type": "object", "properties": { "type": { "const": "LineString" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "minItems": 2, "description": "GeoJSON positions in longitude, latitude order. Road geometry; original pins are returned separately." } }, "required": [ "type", "coordinates" ] }, "RouteStep": { "type": "object", "properties": { "instruction": { "type": "string" }, "distanceMeters": { "type": "number", "minimum": 0 }, "durationSeconds": { "type": "number", "minimum": 0 }, "type": { "type": "integer" }, "streetNames": { "type": [ "array", "null" ], "items": { "type": "string" } }, "beginShapeIndex": { "type": "integer", "minimum": 0 }, "endShapeIndex": { "type": "integer", "minimum": 0 }, "legIndex": { "type": "integer", "minimum": 0 } }, "required": [ "instruction", "distanceMeters", "durationSeconds", "type", "streetNames", "beginShapeIndex", "endShapeIndex", "legIndex" ] }, "RouteResponse": { "type": "object", "properties": { "profile": { "type": "string", "enum": [ "driving", "walking", "cycling" ] }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Point" }, "minItems": 2, "maxItems": 10, "description": "Original requested coordinates, unchanged." }, "snappedLocations": { "type": "array", "items": { "$ref": "#/components/schemas/Point" }, "minItems": 2, "maxItems": 10, "description": "Actual start/end coordinates of each road leg." }, "distanceMeters": { "type": "number", "minimum": 0 }, "durationSeconds": { "type": "number", "minimum": 0 }, "geometry": { "$ref": "#/components/schemas/RouteGeometry" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/RouteStep" } }, "traffic": { "const": "not_included" }, "coverage": { "type": "string", "enum": [ "world", "americas", "latin_america", "unspecified" ] }, "attribution": { "type": "string" }, "cached": { "type": "boolean" }, "tookMs": { "type": "number", "minimum": 0 } }, "required": [ "profile", "locations", "snappedLocations", "distanceMeters", "durationSeconds", "geometry", "steps", "traffic", "coverage", "attribution" ] }, "MatrixResponse": { "type": "object", "properties": { "durationSeconds": { "type": "array", "items": { "type": "array", "items": { "type": [ "number", "null" ], "minimum": 0, "description": "Null when no reachable path exists for this pair." }, "minItems": 1, "maxItems": 10 }, "minItems": 1, "maxItems": 10 }, "distanceMeters": { "type": "array", "items": { "type": "array", "items": { "type": [ "number", "null" ], "minimum": 0, "description": "Null when no reachable path exists for this pair." }, "minItems": 1, "maxItems": 10 }, "minItems": 1, "maxItems": 10 }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Point" }, "minItems": 1, "maxItems": 10 }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Point" }, "minItems": 1, "maxItems": 10 }, "traffic": { "const": "not_included" }, "coverage": { "type": "string", "enum": [ "world", "americas", "latin_america", "unspecified" ] }, "attribution": { "type": "string" } }, "required": [ "durationSeconds", "distanceMeters", "sources", "targets", "traffic", "coverage", "attribution" ] }, "BatchResult": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "query": { "type": "string" }, "status": { "const": "ok" }, "result": { "$ref": "#/components/schemas/Location" } }, "required": [ "id", "query", "status", "result" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "query": { "type": "string" }, "status": { "const": "not_found" } }, "required": [ "id", "query", "status" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "query": { "type": "string" }, "status": { "const": "error" }, "code": { "type": "string", "enum": [ "search_unavailable", "invalid_response" ] } }, "required": [ "id", "query", "status", "code" ] } ] }, "BatchResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BatchResult" }, "minItems": 1, "maxItems": 10 }, "count": { "type": "integer", "minimum": 1, "maximum": 10 }, "attribution": { "type": "string" } }, "required": [ "results", "count", "attribution" ] }, "CoverageResponse": { "type": "object", "properties": { "covered": { "type": "boolean" }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/Zone" }, "maxItems": 20 }, "point": { "$ref": "#/components/schemas/Point" }, "feePolicy": { "const": "all_matching_zones" } }, "required": [ "covered", "matches", "point", "feePolicy" ] }, "StreetMatch": { "type": "object", "additionalProperties": false, "properties": { "coordinateType": { "const": "street_reference", "description": "A reference to a street, not an exact doorway. Municipal references are label positions in the published working map." }, "requestedHouseNumber": { "type": "string" }, "houseNumberMatched": { "const": false }, "sourceURL": { "type": "string" }, "sourceDate": { "type": "string", "description": "Source snapshot/document date, not the request date." } }, "required": [ "coordinateType", "houseNumberMatched", "sourceURL", "sourceDate" ] } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Mapora API key" } } } }