> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-agents/cli/command-reference/lds.md).

# lds

CARTO Location Data Services from the terminal: geocoding, reverse geocoding, isolines, routing, and origin-destination matrices. Each subcommand uses the provider configured for your account and counts against its quota. Run [`carto lds capabilities`](#carto-lds-capabilities) to see which provider serves each operation and how much quota remains.

```bash
carto lds geocode "350 5th Ave, New York, NY"
carto lds reverse-geocode 40.4168 -3.7038
carto lds isolines "-3.7038,40.4168" --mode car --range 300,600 --range-type time
carto lds routing "-3.7038,40.4168" "-3.6883,40.4531" --mode car
carto lds od-matrix --origin "-3.70,40.41" --destination "-3.68,40.45"
carto lds capabilities
```

{% hint style="info" %}
Coordinates are written `lon,lat` wherever they are packed into a single value (isolines, routing, od-matrix). `reverse-geocode` is the exception: it takes `lat` and `lon` as two separate arguments.
{% endhint %}

Every subcommand accepts `--options <json>` for provider-specific advanced options, and `--json` for machine-readable output.

## `carto lds geocode [address...]`

Geocode one or more addresses into coordinates. Pass addresses as arguments (repeat to batch them into a single request) or read them from a file with `--file`, one per line. At least one address is required, from arguments or `--file`.

```bash
# Single address
carto lds geocode "350 5th Ave, New York, NY"

# Batch several, biased to a country
carto lds geocode "Cibeles, Madrid" "Sagrada Familia, Barcelona" --country ES

# From a file, one address per line, best match only
carto lds geocode --file addresses.txt --limit 1
```

| Option             | Description                                                                  |
| ------------------ | ---------------------------------------------------------------------------- |
| `--country <code>` | ISO 3166-1 country code to bias or restrict results (e.g. `US`).             |
| `--limit <n>`      | Maximum candidates per address.                                              |
| `--file <path>`    | Read addresses from a file, one per line (added to any passed as arguments). |
| `--options <json>` | Provider-specific advanced options as a JSON object.                         |

## `carto lds reverse-geocode <lat> <lon>`

Turn a coordinate into an address or place name. Latitude and longitude are separate arguments.

```bash
carto lds reverse-geocode 40.4168 -3.7038
carto lds reverse-geocode 40.4168 -3.7038 --lang es --json
```

| Option             | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| `--lang <code>`    | Result language where the provider supports it (e.g. `es`). |
| `--limit <n>`      | Maximum candidates.                                         |
| `--options <json>` | Provider-specific advanced options as a JSON object.        |

## `carto lds isolines <origin>`

Compute an isoline (catchment area) around one origin, given as `lon,lat`.

```bash
# 5- and 10-minute drive-time catchments
carto lds isolines "-3.7038,40.4168" --mode car --range 300,600 --range-type time

# 1 km walking catchment
carto lds isolines "-3.7038,40.4168" --mode walk --range 1000 --range-type distance
```

| Option                | Description                                                                         |
| --------------------- | ----------------------------------------------------------------------------------- |
| `--mode <mode>`       | (Required) Travel mode, provider-dependent (e.g. `car`, `walk`, `bike`).            |
| `--range <values>`    | (Required) Comma-separated range values: seconds for `time`, meters for `distance`. |
| `--range-type <type>` | (Required) Whether `--range` is `time` or `distance`.                               |
| `--options <json>`    | Provider-specific advanced options as a JSON object.                                |

## `carto lds routing <origin> <destination>`

Compute a route between two points, each given as `lon,lat`, optionally via intermediate waypoints.

```bash
carto lds routing "-3.7038,40.4168" "-3.6883,40.4531" --mode car

# Via waypoints, with full geometry
carto lds routing "-3.70,40.41" "-3.68,40.45" \
  --mode car \
  --waypoints "-3.69,40.42:-3.685,40.44" \
  --overview full
```

| Option                        | Description                                                                       |
| ----------------------------- | --------------------------------------------------------------------------------- |
| `--mode <mode>`               | (Required) Travel mode, provider-dependent (e.g. `car`, `pedestrian`, `bicycle`). |
| `--waypoints <points>`        | Intermediate stops as `lon,lat:lon,lat` (colon-separated `lon,lat` pairs).        |
| `--overview <detail>`         | Geometry detail: `simplified` (default) or `full`.                                |
| `--simplify-tolerance <m>`    | Fixed simplification tolerance in meters. Ignored with `--overview full`.         |
| `--include-provider-geometry` | Include the provider's raw geometry in the response metadata.                     |
| `--options <json>`            | Provider-specific advanced options as a JSON object.                              |

## `carto lds od-matrix`

Compute an origin-destination travel-time and distance matrix. TravelTime provider only. Supply origins and destinations either as repeatable point flags or as JSON arrays of `[lon,lat]` pairs.

```bash
# Repeatable point flags
carto lds od-matrix \
  --origin "-3.70,40.41" --origin "-3.69,40.42" \
  --destination "-3.68,40.45"

# JSON arrays of [lon,lat] pairs
carto lds od-matrix \
  --origins-json '[[-3.70,40.41],[-3.69,40.42]]' \
  --destinations-json '[[-3.68,40.45]]'
```

| Option                       | Description                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------- |
| `--origin <lon,lat>`         | An origin point. Repeatable.                                                 |
| `--destination <lon,lat>`    | A destination point. Repeatable.                                             |
| `--origins-json <json>`      | Origins as a JSON array of `[lon,lat]` pairs. Replaces `--origin`.           |
| `--destinations-json <json>` | Destinations as a JSON array of `[lon,lat]` pairs. Replaces `--destination`. |
| `--mode <mode>`              | Travel mode, provider-dependent.                                             |
| `--options <json>`           | Provider-specific advanced options as a JSON object.                         |

## `carto lds capabilities`

Show the account's LDS provider for each operation and its quota (annual, used, remaining).

```bash
carto lds capabilities
carto lds capabilities --json
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.carto.com/carto-for-agents/cli/command-reference/lds.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.