{"openapi":"3.1.0","info":{"title":"MapRouter API","version":"1.0.0","description":"Maps, geocoding and time zones from OpenStreetMap data, paid from prepaid credits. Responses carry X-MR-Credits-Used and X-MR-Balance. Map data © OpenStreetMap contributors."},"servers":[{"url":"https://api.maprouter.dev"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"mr_pk_ (publishable) or mr_sk_ (secret) key"},"queryKey":{"type":"apiKey","in":"query","name":"key","description":"For URLs a browser fetches directly"}},"schemas":{"FeatureCollection":{"type":"object","properties":{"type":{"const":"FeatureCollection"},"features":{"type":"array","items":{"type":"object","properties":{"type":{"const":"Feature"},"geometry":{"type":"object","properties":{"type":{"const":"Point"},"coordinates":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}},"properties":{"type":"object","additionalProperties":true}}}},"attribution":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message","docs_url"],"properties":{"code":{"type":"string","enum":["insufficient_credits","key_cap_reached","missing_key","invalid_key","origin_not_allowed","key_type_not_allowed","invalid_request","raise_not_allowed","not_found","request_too_large","rate_limited","feature_disabled","internal_error"]},"message":{"type":"string"},"docs_url":{"type":"string"}}}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/geocode":{"get":{"summary":"Forward geocoding (10 credits)","security":[{"bearer":[]}],"parameters":[{"name":"q","in":"query","required":true,"description":"Address or place","schema":{"type":"string","maxLength":300}},{"name":"limit","in":"query","required":false,"description":"Results, 1 to 20 (default 5)","schema":{"type":"integer","minimum":1,"maximum":20}},{"name":"countries","in":"query","required":false,"description":"Comma-separated ISO 3166-1 alpha-2 codes","schema":{"type":"string","example":"GB,IE"}},{"name":"bbox","in":"query","required":false,"description":"minLon,minLat,maxLon,maxLat","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Label language","schema":{"type":"string","enum":["en","de","fr","it","default"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureCollection"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/autocomplete":{"get":{"summary":"Search-as-you-type (2 credits)","security":[{"bearer":[]},{"queryKey":[]}],"parameters":[{"name":"q","in":"query","required":true,"description":"Address or place","schema":{"type":"string","maxLength":300}},{"name":"limit","in":"query","required":false,"description":"Results, 1 to 20 (default 5)","schema":{"type":"integer","minimum":1,"maximum":20}},{"name":"countries","in":"query","required":false,"description":"Comma-separated ISO 3166-1 alpha-2 codes","schema":{"type":"string","example":"GB,IE"}},{"name":"bbox","in":"query","required":false,"description":"minLon,minLat,maxLon,maxLat","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Label language","schema":{"type":"string","enum":["en","de","fr","it","default"]}},{"name":"focus","in":"query","required":false,"description":"lat,lon to prefer nearby results","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureCollection"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/reverse":{"get":{"summary":"Reverse geocoding (10 credits)","security":[{"bearer":[]}],"parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lon","in":"query","required":true,"description":"Longitude","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"lang","in":"query","required":false,"description":"Label language","schema":{"type":"string","enum":["en","de","fr","it","default"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureCollection"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/geocode/batch":{"post":{"summary":"Batch geocoding, up to 1,000 queries (8 credits each)","security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["queries"],"properties":{"queries":{"type":"array","maxItems":1000,"items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"q":{"type":"string"},"limit":{"type":"integer"},"countries":{"type":"string"},"bbox":{"type":"string"},"lang":{"type":"string"}},"required":["q"]}]}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array"},"failed":{"type":"integer"}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/timezone":{"get":{"summary":"Time zone at a point (1 credit)","security":[{"bearer":[]},{"queryKey":[]}],"parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lon","in":"query","required":true,"description":"Longitude","schema":{"type":"number","minimum":-180,"maximum":180}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"timezone":{"type":"string"},"utc_offset":{"type":"string"},"utc_offset_seconds":{"type":"integer"},"dst":{"type":"boolean"},"local_time":{"type":"string"}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/styles/{name}.json":{"get":{"summary":"MapLibre style with the key baked in (free)","security":[{"bearer":[]},{"queryKey":[]}],"parameters":[{"name":"name","in":"path","required":true,"description":"Style","schema":{"type":"string","enum":["survey","survey-dark","light","dark","white","grayscale","black"]}},{"name":"lang","in":"query","required":false,"description":"Label language","schema":{"type":"string","enum":["en","de","fr","it","default"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/tiles/{z}/{x}/{y}.mvt":{"get":{"summary":"Vector tile (1 credit)","security":[{"bearer":[]},{"queryKey":[]}],"parameters":[{"name":"z","in":"path","required":true,"description":"z","schema":{"type":"integer","minimum":0}},{"name":"x","in":"path","required":true,"description":"x","schema":{"type":"integer","minimum":0}},{"name":"y","in":"path","required":true,"description":"y","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Mapbox Vector Tile","content":{"application/vnd.mapbox-vector-tile":{}}},"204":{"description":"No data here"},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/tiles.json":{"get":{"summary":"TileJSON (free)","security":[{"bearer":[]},{"queryKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/account/usage":{"get":{"summary":"Balance, free tier and key caps (free)","security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/projects":{"post":{"summary":"Create a project with a publishable and a secret key (free)","security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"origins":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Created"},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/keys":{"get":{"summary":"Active keys, without secrets (free)","security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/keys/{id}/budget":{"post":{"summary":"Lower a key's caps; raising is refused (free)","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Key id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"daily_cap":{"type":"integer","minimum":0},"monthly_cap":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}}}}