Skip to main content

Mapconvert API

Get an API key

Convert a Google Maps URL to lat & long with one JSON request.

POSThttps://api.mapconvert.dev/coordinates

Quickstart

Send a POST with a JSON body. Try out the snippets.

Example
curl https://api.mapconvert.dev/coordinates \  -H 'Authorization: Bearer mc_demo_public' \  -H 'Content-Type: application/json' \  -d '{"url": "https://www.google.com/maps/place/48.8584,2.2945"}'
Response

Run the request to see the live response.

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.

Header
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.

urlstringrequired
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.
includeResolvedUrlbooleanoptional
Set to true to include resolvedUrl in the response. Defaults to false.
includeNamebooleanoptional
Set to true to include name in the response when a place name is known. Defaults to false.
Example body
{  "url": "https://www.google.com/maps/place/48.8584,2.2945",  "includeResolvedUrl": true}

Response

A successful call returns HTTP 200 and a JSON object.

latdoublerequired
Latitude in decimal degrees, from -90.0 to 90.0.
lngdoublerequired
Longitude in decimal degrees, from -180.0 to 180.0.
resolvedUrlstringoptional
Only present when includeResolvedUrl is true. The URL after short-link expansion, or the submitted URL when it did not need expanding.
namestringoptional
Only present when includeName is true and the place has a known name.
200 OK
{  "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.

urlsstring[]required
1 to 10,000 Google Maps URLs.
includeResolvedUrlbooleanoptional
Set to true to add resolvedUrl to each converted entry. Defaults to false.
includeNamebooleanoptional
Set to true to add name to each converted entry when a place name is known. Defaults to false.
Example body
{  "urls": [    "https://maps.app.goo.gl/uUbxXXE3WX3P4pKF7",    "https://maps.google.com/?cid=4603134393150933480"  ]}

Response

The job is stored and HTTP 202 is returned.

idstringrequired
The job id. Use it to read the job.
202 Accepted
{  "id": "6f1c2b4e-8a0d-4e5f-9c31-0b7a1d2e3f40"}

GET /coordinates/batch/:id

Request

No body. An unknown id returns 404 not_found.

idstringrequired
In the path. The id returned when the batch was created.
showIncompleteResultsbooleanoptional
In the query string. Set to true to list the URLs converted so far while the job runs. Defaults to false.
Example path
/coordinates/batch/6f1c2b4e-8a0d-4e5f-9c31-0b7a1d2e3f40?showIncompleteResults=true

Response

Returns HTTP 200 and a JSON object.

statusstringrequired
queued, converting, or complete.
donenumberrequired
How many URLs are done processing.
totalnumberrequired
How many URLs the job contains in total.
coordinatesarrayrequired
Empty until status is complete, unless showIncompleteResults is true. A complete job has one entry per URL, in input order. Each entry has url and exactly one of result or error. result holds lat and lng. error holds code and message. If your credits run out, the job completes and the unconverted URLs fail with INSUFFICIENT_CREDITS.
200 OK, while converting
{  "status": "converting",  "done": 1,  "total": 2,  "coordinates": []}
200 OK, complete
{  "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.

errorstringrequired
One of the error codes below.
messagestringrequired
A short explanation of that code.
400 Bad Request
{  "error": "DISALLOWED_HOST",  "message": "Host is not a Google Maps URL: example.com"}
Error codes13
INVALID_JSONHTTP 400
The request body is empty or is not valid JSON.
INVALID_URLHTTP 400
url is missing, empty, or not a valid URL. For a batch, urls is not a list of 1 to 10,000 entries.
DISALLOWED_HOSTHTTP 400
The URL does not belong to a Google Maps domain.
UNAUTHORIZEDHTTP 401
The API key is missing or not valid.
INSUFFICIENT_CREDITSHTTP 402
Your balance does not cover this request. Add credits.
BATCH_NOT_ALLOWEDHTTP 403
The public demo key cannot convert a batch. Use your own key.
PAYLOAD_TOO_LARGEHTTP 413
The request body is over 8,192 bytes, or 10 MiB for a batch.
COORDS_NOT_FOUNDHTTP 422
No coordinates could be found for this URL.
UNCERTAIN_URLHTTP 422
The URL does not point to one specific place, for example a name search.
RATE_LIMITEDHTTP 429
The public demo key allows one request per minute. Use your own key.
INTERNALHTTP 500
Something unexpected went wrong on our side.
RESOLVE_FAILEDHTTP 502
A short link could not be expanded.
TIMEOUTHTTP 504
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.