> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Geocodio API reference

> API reference for the Geocodio plugin in Corsair: every `geocodio.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Distance

### fromOrigin

`distance.fromOrigin`

Measure driving or straight-line distance and duration from one origin to many destinations, optionally filtering and sorting by either

**Risk:** `read`

```ts theme={null}
await corsair.geocodio.api.distance.fromOrigin({ origin: '1109 N Highland St, Arlington, VA 22201', destinations: ['1600 Pennsylvania Ave NW, Washington, DC 20500'], mode: 'driving' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `origin` | `string` | Yes | The starting address or `lat,lng` pair |
| `destinations` | `string[]` | Yes | The addresses or `lat,lng` pairs to measure from the origin |
| `mode` | `driving \| haversine \| straightline` | No | `driving` follows roads and gives a duration; `haversine` and `straightline` are the as-the-crow-flies distance |
| `units` | `miles \| km` | No | Which distance figure to use |
| `max_results` | `number` | No | Caps the destinations returned |
| `max_distance` | `number` | No | Drops destinations farther than this |
| `max_duration` | `number` | No | Drops destinations slower than this |
| `min_distance` | `number` | No | Drops destinations nearer than this |
| `min_duration` | `number` | No | Drops destinations faster than this |
| `order_by` | `distance \| duration` | No | Which figure to sort by |
| `sort_order` | `asc \| desc` | No | Sort direction |
| `country` | `string` | No | Restricts and formats the lookup as `US`, `CA`, `MX`, `GB`, `AU` or `NZ`, which also changes how an address is parsed |
| `enterprise` | `boolean` | No | Uses the enterprise host |

The route accepts `driving`, `haversine` and `straightline`; only `driving` returns a duration.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `origin` | `Record<string, any>` | No | — |
| `mode` | `string` | No | — |
| `destinations` | `object[]` | Yes | — |
| `_warnings` | `string[]` | No | — |

> [accordion] destinations full type
>
> ```ts theme={null}
> {
>   query?: string,
>   location?: number[],
>   id?: string | null,
>   distance_miles?: number,
>   distance_km?: number,
>   duration_seconds?: number | null,
>   geocode?: Record<string, any>
> }[]
> ```

***

### matrix

`distance.matrix`

Measure every origin against every destination, or pair each origin with one destination, in a single request

**Risk:** `read`

```ts theme={null}
await corsair.geocodio.api.distance.matrix({ origins: ['38.886665,-77.094733'], destinations: ['38.8977,-77.0365'] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `origins` | `string[]` | Yes | The starting addresses or `lat,lng` pairs, one row each |
| `destinations` | `string[]` | Yes | The addresses or `lat,lng` pairs, one column each |
| `calculation_type` | `matrix \| pairs` | No | `matrix` measures every origin against every destination; `pairs` pairs each origin with the destination at the same position |
| `mode` | `driving \| haversine \| straightline` | No | `driving` follows roads and gives a duration; `haversine` and `straightline` are the as-the-crow-flies distance |
| `units` | `miles \| km` | No | Which distance figure to order and filter by |
| `max_results` | `number` | No | Caps the cells returned |
| `max_distance` | `number` | No | Drops cells farther than this |
| `max_duration` | `number` | No | Drops cells slower than this |
| `min_distance` | `number` | No | Drops cells nearer than this |
| `min_duration` | `number` | No | Drops cells faster than this |
| `order_by` | `distance \| duration` | No | Which figure to sort by |
| `sort_order` | `asc \| desc` | No | Sort direction |

`calculation_type: pairs` pairs each origin with the destination at the same position instead of crossing them.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `mode` | `string` | No | — |
| `results` | `object[]` | Yes | — |
| `_warnings` | `string[]` | No | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   origin?: Record<string, any>,
>   destinations: {
>     query?: string,
>     location?: number[],
>     id?: string | null,
>     distance_miles?: number,
>     distance_km?: number,
>     duration_seconds?: number | null,
>     geocode?: Record<string, any>
>   }[]
> }[]
> ```

***

## Geocode

### batch

`geocode.batch`

Geocode up to 10,000 addresses in one request, answered in the order they were sent

**Risk:** `read`

```ts theme={null}
await corsair.geocodio.api.geocode.batch({ addresses: ['1109 N Highland St, Arlington, VA 22201'] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `addresses` | `string[]` | Yes | The addresses to geocode in one request |
| `fields` | `string[]` | No | Data appends to add to each result, such as `timezone`, `congressional_district`, `stateleg`, `school`, `census`, `zip4`, or a Census ACS name |
| `country` | `string` | No | Restricts and formats the lookup as `US`, `CA`, `MX`, `GB`, `AU` or `NZ`, which also changes how an address is parsed |
| `enterprise` | `boolean` | No | Uses the enterprise host |

Up to 10,000 addresses in one POST, answered in order as `{ query, response: { results } }` entries.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[]` | Yes | — |
| `_warnings` | `string[]` | No | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   query: string,
>   response: {
>     results: {
>       stable_address_key?: string | null,
>       address_components: {
>         number?: string,
>         predirectional?: string,
>         street?: string,
>         suffix?: string,
>         postdirectional?: string,
>         unit_type?: string,
>         unit_number?: string,
>         formatted_street?: string,
>         city?: string,
>         county?: string,
>         state_province?: string,
>         postal_code?: string,
>         country?: string,
>         nation?: string,
>         building_name?: string,
>         sublocality?: string
>       },
>       address_lines?: string[],
>       formatted_address: string,
>       location: {
>         lat: number,
>         lng: number
>       },
>       accuracy: number,
>       accuracy_type: string,
>       match_type?: string | null,
>       source?: string,
>       fields?: Record<string, any>,
>       destinations?: {
>         query?: string,
>         location?: number[],
>         id?: string | null,
>         distance_miles?: number,
>         distance_km?: number,
>         duration_seconds?: number | null,
>         geocode?: Record<string, any>
>       }[]
>     }[],
>     _warnings?: string[],
>     error?: string,
>     reference?: string
>   }
> }[]
> ```

***

### batchReverse

`geocode.batchReverse`

Reverse geocode up to 10,000 coordinate pairs in one request, answered in the order they were sent

**Risk:** `read`

```ts theme={null}
await corsair.geocodio.api.geocode.batchReverse({ coordinates: ['38.886665,-77.094733'] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `coordinates` | `string[]` | Yes | The `lat,lng` pairs to reverse geocode in one request |
| `fields` | `string[]` | No | Data appends to add to each result, such as `timezone`, `congressional_district`, `stateleg`, `school`, `census`, `zip4`, or a Census ACS name |
| `country` | `string` | No | Restricts and formats the lookup as `US`, `CA`, `MX`, `GB`, `AU` or `NZ`, which also changes how an address is parsed |
| `enterprise` | `boolean` | No | Uses the enterprise host |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[]` | Yes | — |
| `_warnings` | `string[]` | No | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   query: string,
>   response: {
>     results: {
>       stable_address_key?: string | null,
>       address_components: {
>         number?: string,
>         predirectional?: string,
>         street?: string,
>         suffix?: string,
>         postdirectional?: string,
>         unit_type?: string,
>         unit_number?: string,
>         formatted_street?: string,
>         city?: string,
>         county?: string,
>         state_province?: string,
>         postal_code?: string,
>         country?: string,
>         nation?: string,
>         building_name?: string,
>         sublocality?: string
>       },
>       address_lines?: string[],
>       formatted_address: string,
>       location: {
>         lat: number,
>         lng: number
>       },
>       accuracy: number,
>       accuracy_type: string,
>       match_type?: string | null,
>       source?: string,
>       fields?: Record<string, any>,
>       destinations?: {
>         query?: string,
>         location?: number[],
>         id?: string | null,
>         distance_miles?: number,
>         distance_km?: number,
>         duration_seconds?: number | null,
>         geocode?: Record<string, any>
>       }[]
>     }[],
>     _warnings?: string[],
>     error?: string,
>     reference?: string
>   }
> }[]
> ```

***

### forward

`geocode.forward`

Turn an address into coordinates, with a confidence score, the accuracy type that says how the match was made, and the parsed components. Data appends such as timezone or congressional district come back under `fields`

**Risk:** `read`

```ts theme={null}
await corsair.geocodio.api.geocode.forward({ q: '1109 N Highland St, Arlington, VA 22201', fields: ['timezone'] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `q` | `string` | No | A single-line address, such as `1109 N Highland St, Arlington, VA 22201` |
| `street` | `string` | No | The street line, without the city |
| `street2` | `string` | No | The unit, suite or floor |
| `city` | `string` | No | The city |
| `county` | `string` | No | The county |
| `state_province` | `string` | No | The state or province |
| `postal_code` | `string` | No | The ZIP or postal code |
| `country` | `string` | No | Restricts and formats the lookup as `US`, `CA`, `MX`, `GB`, `AU` or `NZ`, which also changes how an address is parsed |
| `limit` | `number` | No | How many matches to return, at most 100 |
| `fields` | `string[]` | No | Data appends to add to each result, such as `timezone`, `congressional_district`, `stateleg`, `school`, `census`, `zip4`, or a Census ACS name |
| `enterprise` | `boolean` | No | Uses api.enterprise.geocod.io, for accounts that have one |

Send either `q` or the components; `fields` appends data such as `timezone` under `fields`.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[]` | Yes | — |
| `_warnings` | `string[]` | No | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   stable_address_key?: string | null,
>   address_components: {
>     number?: string,
>     predirectional?: string,
>     street?: string,
>     suffix?: string,
>     postdirectional?: string,
>     unit_type?: string,
>     unit_number?: string,
>     formatted_street?: string,
>     city?: string,
>     county?: string,
>     state_province?: string,
>     postal_code?: string,
>     country?: string,
>     nation?: string,
>     building_name?: string,
>     sublocality?: string
>   },
>   address_lines?: string[],
>   formatted_address: string,
>   location: {
>     lat: number,
>     lng: number
>   },
>   accuracy: number,
>   accuracy_type: string,
>   match_type?: string | null,
>   source?: string,
>   fields?: Record<string, any>,
>   destinations?: {
>     query?: string,
>     location?: number[],
>     id?: string | null,
>     distance_miles?: number,
>     distance_km?: number,
>     duration_seconds?: number | null,
>     geocode?: Record<string, any>
>   }[]
> }[]
> ```

***

### parse

`geocode.parse`

Split an address into its components without geocoding it, so it costs no lookup

**Risk:** `read`

```ts theme={null}
await corsair.geocodio.api.geocode.parse({ q: '1109 N Highland St, Arlington, VA 22201' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `q` | `string` | Yes | An address to split into its components, without geocoding it |

Splits an address without geocoding it, so it costs no lookup.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `address_components` | `object` | Yes | — |
| `formatted_address` | `string` | No | — |

> [accordion] address\_components full type
>
> ```ts theme={null}
> {
>   number?: string,
>   predirectional?: string,
>   street?: string,
>   suffix?: string,
>   postdirectional?: string,
>   unit_type?: string,
>   unit_number?: string,
>   formatted_street?: string,
>   city?: string,
>   county?: string,
>   state_province?: string,
>   postal_code?: string,
>   country?: string,
>   nation?: string,
>   building_name?: string,
>   sublocality?: string
> }
> ```

***

### reverse

`geocode.reverse`

Turn a latitude and longitude into the nearest address, with the same confidence and components a forward lookup returns

**Risk:** `read`

```ts theme={null}
await corsair.geocodio.api.geocode.reverse({ q: '38.886665,-77.094733' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `q` | `string` | Yes | A `lat,lng` pair, such as `38.886665,-77.094733` |
| `fields` | `string[]` | No | Data appends to add to each result, such as `timezone`, `congressional_district`, `stateleg`, `school`, `census`, `zip4`, or a Census ACS name |
| `enterprise` | `boolean` | No | Uses the enterprise host |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[]` | Yes | — |
| `_warnings` | `string[]` | No | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   stable_address_key?: string | null,
>   address_components: {
>     number?: string,
>     predirectional?: string,
>     street?: string,
>     suffix?: string,
>     postdirectional?: string,
>     unit_type?: string,
>     unit_number?: string,
>     formatted_street?: string,
>     city?: string,
>     county?: string,
>     state_province?: string,
>     postal_code?: string,
>     country?: string,
>     nation?: string,
>     building_name?: string,
>     sublocality?: string
>   },
>   address_lines?: string[],
>   formatted_address: string,
>   location: {
>     lat: number,
>     lng: number
>   },
>   accuracy: number,
>   accuracy_type: string,
>   match_type?: string | null,
>   source?: string,
>   fields?: Record<string, any>,
>   destinations?: {
>     query?: string,
>     location?: number[],
>     id?: string | null,
>     distance_miles?: number,
>     distance_km?: number,
>     duration_seconds?: number | null,
>     geocode?: Record<string, any>
>   }[]
> }[]
> ```

***

## Jobs

### delete

`jobs.delete`

Delete a distance job and its stored result

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.geocodio.api.jobs.delete({ identifier: 'abc123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `identifier` | `string` | Yes | The job ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `message` | `string` | No | — |
| `_warnings` | `string[]` | No | — |

***

### get

`jobs.get`

Read one distance job, whose status says whether its result is ready

**Risk:** `read`

```ts theme={null}
await corsair.geocodio.api.jobs.get({ identifier: 'abc123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `identifier` | `string` | Yes | The job ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object` | Yes | — |
| `_warnings` | `string[]` | No | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   identifier: string,
>   name?: string,
>   created_at?: string,
>   origins_type?: string,
>   origins_count?: number,
>   destinations_type?: string,
>   destinations_count?: number,
>   distance_mode?: string,
>   calculation_type?: string,
>   status?: string,
>   download_url?: string | null,
>   total_calculations?: number,
>   calculations_completed?: number,
>   progress?: number,
>   status_message?: string | null,
>   time_left?: string | null,
>   is_expired?: boolean
> }
> ```

***

### list

`jobs.list`

List the asynchronous distance matrix jobs on the account

**Risk:** `read`

```ts theme={null}
await corsair.geocodio.api.jobs.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | The page of jobs to read |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `data` | `object[]` | Yes | — |
| `links` | `Record<string, any>` | No | — |
| `meta` | `Record<string, any>` | No | — |
| `_warnings` | `string[]` | No | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   identifier: string,
>   name?: string,
>   created_at?: string,
>   origins_type?: string,
>   origins_count?: number,
>   destinations_type?: string,
>   destinations_count?: number,
>   distance_mode?: string,
>   calculation_type?: string,
>   status?: string,
>   download_url?: string | null,
>   total_calculations?: number,
>   calculations_completed?: number,
>   progress?: number,
>   status_message?: string | null,
>   time_left?: string | null,
>   is_expired?: boolean
> }[]
> ```

***

## Lists

### all

`lists.all`

List the uploaded spreadsheets and their processing status

**Risk:** `read`

```ts theme={null}
await corsair.geocodio.api.lists.all({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | The page of lists to read |

There is no upload route here, so a new spreadsheet has to be uploaded from the dashboard.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `current_page` | `number` | No | — |
| `current_page_url` | `string \| null` | No | — |
| `per_page` | `number` | No | — |
| `from` | `number` | No | — |
| `to` | `number` | No | — |
| `data` | `object[]` | Yes | — |
| `next_page_url` | `string \| null` | No | — |
| `prev_page_url` | `string \| null` | No | — |
| `first_page_url` | `string \| null` | No | — |
| `path` | `string` | No | — |
| `_warnings` | `string[]` | No | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   id: number,
>   status?: {
>     state?: string,
>     progress?: number,
>     message?: string | null,
>     time_left_description?: string | null,
>     time_left_seconds?: string | number | null
>   },
>   file?: {
>     estimated_rows_count?: number | null,
>     filename?: string | null
>   },
>   fields?: string[],
>   download_url?: string | null,
>   expires_at?: string | null,
>   _warnings?: string[]
> }[]
> ```

***

### delete

`lists.delete`

Delete an uploaded spreadsheet and its results

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.geocodio.api.lists.delete({ id: 148 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `number \| string` | Yes | The list ID, as `lists.all` returns it |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `_warnings` | `string[]` | No | — |

***

### get

`lists.get`

Read one spreadsheet list, whose status and download URL say when its results are ready

**Risk:** `read`

```ts theme={null}
await corsair.geocodio.api.lists.get({ id: 148 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `number \| string` | Yes | The list ID, as `lists.all` returns it |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `number` | Yes | — |
| `status` | `object` | No | — |
| `file` | `object` | No | — |
| `fields` | `string[]` | No | — |
| `download_url` | `string \| null` | No | — |
| `expires_at` | `string \| null` | No | — |
| `_warnings` | `string[]` | No | — |

> [accordion] status full type
>
> ```ts theme={null}
> {
>   state?: string,
>   progress?: number,
>   message?: string | null,
>   time_left_description?: string | null,
>   time_left_seconds?: string | number | null
> }
> ```

> [accordion] file full type
>
> ```ts theme={null}
> {
>   estimated_rows_count?: number | null,
>   filename?: string | null
> }
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.