Location Data Services API

Geocoding, isolines and routing.

Location Data Services turn addresses into coordinates, coordinates into addresses, and points into reachable areas or routes. CARTO proxies a third-party provider and normalizes the response, so you call one endpoint regardless of who serves it.

Usage consumes your organization's LDS quota. Check what is left with GET /v3/lds/stats.

Endpoint	What it does
GET /v3/lds/geocoding/geocode	Geocode an address
GET /v3/lds/geocoding/reverse	Reverse geocode coordinates
POST /v3/lds/geocoding/batch	Geocode a list of addresses
GET /v3/lds/isolines	Get an isoline
GET /v3/lds/routing	Get a route
GET /v3/lds/stats	Get LDS quota usage

The provider is configured per organization, and not every provider supports every operation. Calling one your provider doesn't support returns 400 Unsupported provider.

Response fields also vary by provider — treat anything beyond latitude, longitude and formattedAddress as provider-specific.

Operation	Providers
Geocoding	HERE, Google, Mapbox, TomTom, TravelTime
Isolines	HERE, Mapbox, TomTom, TravelTime
Routing	HERE, TomTom, TravelTime

Geocoding one address or many

Use /geocoding/geocode for a single address, and /geocoding/batch for up to 10,000 in one request. Batch results come back in the same order as the input, and a failed address returns an error on its entry rather than failing the whole request — always check per-entry errors.

To geocode a whole table, use the Analytics Toolbox instead. It handles chunking and writes results back to your warehouse.

Coordinate order

origin and destination take longitude,latitude. waypoints take latitude,longitude, separated by colons — a common source of routes that come back inverted.

Isoline range is in seconds when range_type=time and meters when range_type=distance. HERE and Mapbox accept several comma-separated ranges; TomTom and TravelTime accept one.

Endpoints

Geocode an address

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/lds/geocoding/geocode

Returns coordinates for a street address.

The geocoding provider is configured per organization, so the fields of each result depend on which provider your organization uses.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Query parameters

addressstringRequired

The address to geocode.

Example: Plaza Mayor, Madrid

countrystringOptional

Restrict results to a country. Accepts ISO alpha-2, alpha-3, numeric codes or the English country name.

Example: ES

limitintegerOptional

Maximum number of results.

Default: 1

optionsstringOptional

Provider options as a JSON string, for example {"language":"es-ES"}. Supported keys depend on the provider.

Responses

200

The geocoding results.

application/json

errorstring · nullableOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/lds/geocoding/geocode

HTTPcURLJavaScriptPython

GET /v3/lds/geocoding/geocode?address=text HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "error": null,
    "value": [
      {
        "formattedAddress": "Plaza Mayor, 28012 Madrid, España",
        "latitude": 40.41556,
        "longitude": -3.70739,
        "country": "España",
        "countryCode": "ESP",
        "city": "Madrid",
        "zipcode": "28012",
        "provider": "here"
      }
    ]
  }
]

Reverse geocode coordinates

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/lds/geocoding/reverse

Returns the street address closest to a pair of coordinates.

Unlike GET /v3/lds/geocoding/geocode, this endpoint returns the results directly, without the { error, value } wrapper.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Query parameters

latnumberRequired

Latitude.

Example: 40.40168788033523

lonnumberRequired

Longitude.

Example: -3.6925478219155212

langstringOptional

Language for the result, passed through to the provider — for example es-ES. Accepted values depend on the provider.

optionsstringOptional

Provider options as a JSON string.

Responses

200

The addresses found.

application/json

A geocoding result. Fields depend on the provider configured for your organization — the ones below are the most common.

formattedAddressstringOptional

latitudenumberOptional

longitudenumberOptional

countrystringOptional

countryCodestringOptional

statestringOptional

countystringOptional

citystringOptional

zipcodestringOptional

streetNamestringOptional

streetNumberstringOptional

providerstringOptional

Other propertiesanyOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/lds/geocoding/reverse

HTTPcURLJavaScriptPython

GET /v3/lds/geocoding/reverse?lat=1&lon=1 HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "formattedAddress": "text",
    "latitude": 1,
    "longitude": 1,
    "country": "text",
    "countryCode": "text",
    "state": "text",
    "county": "text",
    "city": "text",
    "zipcode": "text",
    "streetName": "text",
    "streetNumber": "text",
    "provider": "text",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
]

Geocode a list of addresses

post

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/lds/geocoding/batch

Geocodes up to 10,000 addresses in one request.

Results come back in the same order as the input. Individual addresses can fail without failing the request — check the error field of each entry.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Body

application/json

addressesstring[] · max: 10000Required

The addresses to geocode.

countrystringOptional

Restrict results to a country.

limitintegerOptional

Maximum results per address. Has no effect when the provider is Google Maps.

Default: 1

Responses

200

One entry per input address, in the same order. An entry with a non-null error means that address failed.

application/json

errorstring · nullableOptional

statusintegerOptional

Present only when the address failed.

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

429

You went over the rate limit for this API.

application/json

post/v3/lds/geocoding/batch

HTTPcURLJavaScriptPython

POST /v3/lds/geocoding/batch HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "addresses": [
    "Lucero, Madrid",
    "Guadalajara"
  ],
  "country": "ES",
  "limit": 1
}

[
  {
    "error": null,
    "value": [
      {
        "formattedAddress": "text",
        "latitude": 1,
        "longitude": 1,
        "country": "text",
        "countryCode": "text",
        "state": "text",
        "county": "text",
        "city": "text",
        "zipcode": "text",
        "streetName": "text",
        "streetNumber": "text",
        "provider": "text",
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "status": 1
  }
]

Get an isoline

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/lds/isolines

Returns the area reachable from a point within a time or distance budget, as GeoJSON.

Isolines are not available when your organization's provider is Google.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Query parameters

originstringRequired

Origin point as longitude,latitude.

Example: -3.70739,40.41556

modestringRequired

Mode of transport — car, walk or bike. CARTO maps these to the equivalent mode for your provider. Other values are passed through.

Example: car

rangestringRequired

Budget, in seconds when range_type=time and in meters when range_type=distance. HERE and Mapbox accept several comma-separated values; TomTom and TravelTime accept only one.

Example: 300

range_typestring · enumRequiredPossible values:

optionsstringOptional

Provider options as a JSON string.

Responses

200

The isoline, as a GeoJSON FeatureCollection.

application/json

typestring · enumOptionalPossible values:

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/lds/isolines

HTTPcURLJavaScriptPython

GET /v3/lds/isolines?origin=text&mode=text&range=text&range_type=time HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "geometry": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ]
}

Get a route

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/lds/routing

Returns a route between two points.

Routing is only available when your organization's provider is HERE, TomTom or TravelTime.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Query parameters

originstringRequired

Origin as longitude,latitude.

Example: -1.633492,42.811801

destinationstringRequired

Destination as longitude,latitude.

Example: -1.660946,42.824662

modestringRequired

Mode of transport. Accepted values depend on the provider — HERE accepts car, truck, pedestrian, bicycle, scooter, taxi, bus and privateBus; TomTom accepts car, pedestrian, bicycle, motorcycle, truck, taxi, bus and van.

Example: car

waypointsstringOptional

Intermediate points, as colon-separated latitude,longitude pairs. Note the order is the reverse of origin and destination. TravelTime supports at most 9.

Example: -1.648453,42.813442:-1.657621,42.814813

optionsstringOptional

Provider options as a JSON string.

Responses

200

The route.

application/json

errorstring · nullableOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/lds/routing

HTTPcURLJavaScriptPython

GET /v3/lds/routing?origin=text&destination=text&mode=text HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "error": null,
  "value": {
    "origin": [
      1
    ],
    "destination": [
      1
    ],
    "route": null,
    "provider": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

Get LDS quota usage

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/lds/stats

Returns your organization's Location Data Services quota, how much of it has been consumed in the current billing period, and which provider serves each operation.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Responses

200

The quota usage.

application/json

annual_quotanumberOptional

used_quotanumberOptional

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/lds/stats

HTTPcURLJavaScriptPython

GET /v3/lds/stats HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "annual_quota": 100000,
    "used_quota": 1234,
    "providers": {
      "geocoding": "here",
      "isolines": "here",
      "routing": "tomtom"
    }
  }
]