# Geocodio

Geocodio provides straightforward and easy-to-use geocoding, reverse geocoding, and data matching services for US and Canadian addresses.

- **Category:** developer tools
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 7
- **Triggers:** 0
- **Slug:** `GEOCODIO`
- **Version:** 20260312_00

## Tools

### Batch Reverse Geocode

**Slug:** `GEOCODIO_BATCH_REVERSE_GEOCODE`

Tool to batch reverse geocode up to 10,000 coordinates in one request. Use when you need addresses for many lat/lon pairs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max number of candidate results per input; 0 means no limit. Must be non-negative. |
| `fields` | string | No | Comma-separated data-append codes to include (e.g., 'cd,stateleg'). |
| `coordinates` | array | Yes | List of 'latitude,longitude' strings. Latitude first. Up to 10,000 items. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Geocodio List

**Slug:** `GEOCODIO_DELETE_LIST`

Permanently deletes a Geocodio spreadsheet list by its ID. Use this to cancel a processing list job or remove a completed list. This action is destructive and cannot be undone. The list_id must be obtained from the lists API or from when the list was created.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `list_id` | integer | Yes | The unique numeric ID of the Geocodio list to delete. Obtain this from the lists API (GET /lists) or from the response when creating a list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Batch Forward Geocode

**Slug:** `GEOCODIO_GEOCODE_BATCH`

Tool to batch geocode up to 10,000 addresses to coordinates in one request. Use when you need to convert multiple addresses to lat/lon coordinates. Optionally calculates distances to specified destinations for each geocoded result.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return per address; 0 means no limit. Must be non-negative. |
| `fields` | string | No | Comma-separated list of data-append codes to include (e.g., 'cd,timezone'). |
| `addresses` | array | Yes | List of address strings to geocode. Up to 10,000 addresses. |
| `destinations` | array | No | Array of destination locations for distance calculation. Each destination can be a coordinate string ('lat,lng' or 'lat,lng,id') or a geocodable address string. |
| `distance_mode` | string ("driving" | "straightline") | No | Distance calculation mode. Defaults to 'driving'. |
| `distance_units` | string ("miles" | "km") | No | Unit of measurement for distance filtering. Defaults to 'miles'. |
| `distance_order_by` | string ("distance" | "duration") | No | Field to sort destinations by. Defaults to 'distance'. |
| `distance_sort_order` | string ("asc" | "desc") | No | Sort order for destinations. Defaults to 'asc'. |
| `distance_max_results` | integer | No | Maximum number of destinations to return per geocoded result. |
| `distance_max_distance` | number | No | Maximum distance filter (in specified units). |
| `distance_max_duration` | integer | No | Maximum duration filter in seconds (only applies to driving mode). |
| `distance_min_distance` | number | No | Minimum distance filter (in specified units). |
| `distance_min_duration` | integer | No | Minimum duration filter in seconds (only applies to driving mode). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Google Maps Compatible Geocode

**Slug:** `GEOCODIO_GEOCODE_GOOGLE_MAPS_COMPATIBLE`

Tool to geocode addresses using Google Maps-compatible API format. Use when you need a drop-in replacement for Google Maps Geocoding API for US and Canada addresses.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | string | Yes | Your Geocodio API key |
| `latlng` | string | No | Latitude,longitude pair (for reverse geocoding). Required if address is not provided. |
| `address` | string | No | Address to geocode (for forward geocoding). Required if latlng is not provided. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Sample Coordinates for Batch Reverse Geocode

**Slug:** `GEOCODIO_GET_COORDINATES_FOR_BATCH_REVERSE_GEOCODE`

Utility tool that returns a predefined list of sample US coordinates (latitude,longitude strings). Use this to obtain ready-to-use coordinate inputs for the batch reverse geocode action. The coordinates cover well-known US landmarks across different cities and states.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Single Forward Geocode

**Slug:** `GEOCODIO_SINGLE_GEOCODE`

Tool to forward geocode a single address. Use when you need coordinates and metadata for one address.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | No | Full address string to geocode; required if components not used |
| `city` | string | No | City name |
| `limit` | integer | No | Maximum number of results; 0 means no limit |
| `state` | string | No | State or province code |
| `county` | string | No | County name |
| `fields` | string | No | Comma-separated list of data appends to include (e.g. 'timezone,cd') |
| `format` | string | No | If 'simple', returns a flattened response schema |
| `street` | string | No | Street address component |
| `country` | string | No | Country context; USA or Canada |
| `street2` | string | No | Secondary street address (unit etc) |
| `postal_code` | string | No | Postal (ZIP) code |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Single Reverse Geocode

**Slug:** `GEOCODIO_SINGLE_REVERSE_GEOCODE`

Tool to reverse geocode a single coordinate. Use when you need to convert one lat,lng to an address.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `lat` | number | Yes | Latitude of the coordinate, between -90 and 90 |
| `lng` | number | Yes | Longitude of the coordinate, between -180 and 180 |
| `limit` | integer | No | Maximum number of results to return; 0 means no limit (default no limit) |
| `fields` | string | No | Comma-separated list of data append codes to include (e.g., 'stateleg,timezone') |
| `format` | string | No | Change output format; only valid value is 'simple' for a simplified response |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |