Skip to main content

API reference

Get an API key

Convert a Google Maps URL to latitude and longitude with one JSON request.

POSThttps://api.mapconvert.dev/coordinates

Quickstart

Send a POST with a JSON body. Edit the request and run it against the live API.

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

Send your API key as a bearer token on every request.

Header
Authorization: Bearer <key>

Sign in to get your key. You can rotate it at any time, and the old key stops working straight away.

The examples on this site use the public demo key mc_demo_public, which allows one request per minute. This can be used for testing.

Request

POST /coordinates with 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.
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.
200 OK
{  "lat": 48.8584,  "lng": 2.2945}

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 codes12
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.
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.
PAYLOAD_TOO_LARGEHTTP 413
The request body is over 8,192 bytes.
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.
Coordinate already on the URL
Answered immediately.
Short-link unfurl
Up to 100 seconds.
Pin, CID, and place-id lookup
Up to 40 seconds.
Billing
Credits are only spent on successful requests. See the rates.