Mapconvert API
Get an API keyConvert a Google Maps URL to lat & long with one JSON request.
https://api.mapconvert.dev/coordinatesQuickstart
Send a POST with a JSON body. Try out the snippets.
Snippets use the public demo key, which allows one request per minute. Get your own key for anything beyond testing.
Authentication
Include your API key as a bearer token on every request.
Authorization: Bearer <key>Sign in to get a personal key.
Single URL
POST /coordinates
Request
Send a JSON body with the header Content-Type: application/json.
url- A Google Maps URL, including short links. Any link that points to one specific place is supported. Name searches and other searches are not. See the supported URL types.
includeResolvedUrl- Set to
trueto includeresolvedUrlin the response. Defaults tofalse. includeName- Set to
trueto includenamein the response when a place name is known. Defaults tofalse.
{ "url": "https://www.google.com/maps/place/48.8584,2.2945", "includeResolvedUrl": true}Response
A successful call returns HTTP 200 and a JSON object.
lat- Latitude in decimal degrees, from -90.0 to 90.0.
lng- Longitude in decimal degrees, from -180.0 to 180.0.
resolvedUrl- Only present when
includeResolvedUrlistrue. The URL after short-link expansion, or the submitted URL when it did not need expanding. name- Only present when
includeNameistrueand the place has a known name.
{ "lat": 48.8584, "lng": 2.2945}Batch of URLs
Convert up to 10,000 URLs in one async job. POST /coordinates/batch returns a job id, and GET /coordinates/batch/:id reads its progress and results. Job results are kept for 24 hours.
POST /coordinates/batch
Request
Send a JSON body with the header Content-Type: application/json.
urls- 1 to 10,000 Google Maps URLs.
includeResolvedUrl- Set to
trueto addresolvedUrlto each converted entry. Defaults tofalse. includeName- Set to
trueto addnameto each converted entry when a place name is known. Defaults tofalse.
{ "urls": [ "https://maps.app.goo.gl/uUbxXXE3WX3P4pKF7", "https://maps.google.com/?cid=4603134393150933480" ]}Response
The job is stored and HTTP 202 is returned.
id- The job id. Use it to read the job.
{ "id": "6f1c2b4e-8a0d-4e5f-9c31-0b7a1d2e3f40"}GET /coordinates/batch/:id
Request
No body. An unknown id returns 404 not_found.
id- In the path. The
idreturned when the batch was created. showIncompleteResults- In the query string. Set to
trueto list the URLs converted so far while the job runs. Defaults tofalse.
/coordinates/batch/6f1c2b4e-8a0d-4e5f-9c31-0b7a1d2e3f40?showIncompleteResults=trueResponse
Returns HTTP 200 and a JSON object.
statusqueued,converting, orcomplete.done- How many URLs are done processing.
total- How many URLs the job contains in total.
coordinates- Empty until
statusiscomplete, unlessshowIncompleteResultsistrue. A complete job has one entry per URL, in input order. Each entry hasurland exactly one ofresultorerror.resultholdslatandlng.errorholdscodeandmessage. If your credits run out, the job completes and the unconverted URLs fail withINSUFFICIENT_CREDITS.
{ "status": "converting", "done": 1, "total": 2, "coordinates": []}{ "status": "complete", "done": 2, "total": 2, "coordinates": [ { "url": "https://maps.app.goo.gl/uUbxXXE3WX3P4pKF7", "result": { "lat": 48.8584, "lng": 2.2945 } }, { "url": "https://maps.google.com/?cid=4603134393150933480", "error": { "code": "COORDS_NOT_FOUND", "message": "Could not find coordinates in the Google Maps URL" } } ]}Errors
Failed calls return a non-2xx status and a JSON body with error code and message.
error- One of the error codes below.
message- A short explanation of that code.
{ "error": "DISALLOWED_HOST", "message": "Host is not a Google Maps URL: example.com"}Error codes13
INVALID_JSON- The request body is empty or is not valid JSON.
INVALID_URLurlis missing, empty, or not a valid URL. For a batch,urlsis not a list of 1 to 10,000 entries.DISALLOWED_HOST- The URL does not belong to a Google Maps domain.
UNAUTHORIZED- The API key is missing or not valid.
INSUFFICIENT_CREDITS- Your balance does not cover this request. Add credits.
BATCH_NOT_ALLOWED- The public demo key cannot convert a batch. Use your own key.
PAYLOAD_TOO_LARGE- The request body is over 8,192 bytes, or 10 MiB for a batch.
COORDS_NOT_FOUND- No coordinates could be found for this URL.
UNCERTAIN_URL- The URL does not point to one specific place, for example a name search.
RATE_LIMITED- The public demo key allows one request per minute. Use your own key.
INTERNAL- Something unexpected went wrong on our side.
RESOLVE_FAILED- A short link could not be expanded.
TIMEOUT- Expanding the URL took too long.
Unknown paths return 404 not_found and other HTTP methods return 405 method_not_allowed.
Limits and timing
Limits that apply to every request, and the longest each kind of lookup can take.
- Request size
- Bodies over 8,192 bytes are rejected with
413. Batch bodies can be up to 10 MiB. - Coordinate-only URL
- Answered immediately when no place ID or feature ID is present.
- Short-link unfurl
- Up to 100 seconds.
- Pin, CID, place-id, and feature-id lookup
- Up to 40 seconds. Takes priority over inline coordinates when a URL carries both.
- Billing
- Credits are only spent on successful requests. See the rates.
- Batch
- Up to 10,000 URLs per job. Jobs are kept for 24 hours.