# Geocodio API Reference for LLMs

Geocodio is a geocoding and data enrichment API for US, Canadian, and Mexican addresses. It converts addresses to coordinates (and vice versa), calculates distances, and appends data like Census information, Congressional districts, and timezones.

**Not a developer?** You can also upload spreadsheets directly at https://www.geocod.io/upload/ — no coding required.

## Quick Reference

- **Base URL:** `https://api.geocod.io/v1.10/`
- **OpenAPI Spec (JSON):** https://api.geocod.io/openapi-spec.json
- **OpenAPI Spec (YAML):** https://api.geocod.io/openapi-spec.yml
- **Full Documentation:** https://www.geocod.io/docs/
- **Dashboard (API keys):** https://dash.geocod.io

---

## Quick Start

**Base URL:** `https://api.geocod.io/v1.10/`

All requests require `&api_key=YOUR_API_KEY`

### Geocoding

| Task | Method | Endpoint | Example |
|------|--------|----------|---------|
| Geocode address | GET | /geocode?q={address} | `?q=1600+Pennsylvania+Ave+NW+DC` |
| Reverse geocode | GET | /reverse?q={lat,lng} | `?q=38.9,-77.0` |
| Batch geocode (up to 10k) | POST | /geocode | Body: `["address1", "address2"]` |
| Batch reverse (up to 10k) | POST | /reverse | Body: `["lat1,lng1", "lat2,lng2"]` |

### Lists API (Spreadsheet Processing)

| Task | Method | Endpoint | Notes |
|------|--------|----------|-------|
| Upload spreadsheet | POST | /lists | Multipart form: `file`, `direction`, `format` |
| Check status | GET | /lists/{id} | Returns `status.state`: PROCESSING or COMPLETED |
| Download results | GET | /lists/{id}/download | Returns CSV (follow redirects) |
| List all | GET | /lists | Paginated |
| Delete | DELETE | /lists/{id} | Auto-deletes after 72 hours anyway |

### Distance API

| Task | Method | Endpoint | Max Size |
|------|--------|----------|----------|
| Single origin | GET | /distance?origin={o}&destinations[]={d} | 100 destinations |
| Distance matrix | POST | /distance-matrix | 10,000 calculations |
| Create async job | POST | /distance-jobs | 50,000 calculations |
| Check job status | GET | /distance-jobs/{id} | — |
| Download job results | GET | /distance-jobs/{id}/download | — |
| Delete job | DELETE | /distance-jobs/{id} | — |

**Note:** Distance and Lists APIs require explicit permission on your API key. Enable at https://dash.geocod.io/apikey

## Authentication

All requests require an API key via query parameter or header:
- Query: `?api_key=YOUR_API_KEY`
- Header: `Authorization: Bearer YOUR_API_KEY`

## Coverage

| Country | Forward Geocoding | Reverse Geocoding | Distance |
|---------|-------------------|-------------------|----------|
| United States | ✓ | ✓ | ✓ |
| Canada | ✓ | ✓ | ✓ |
| Mexico | — | ✓ | — |

---

## Geocoding Endpoints

### Forward Geocoding (Address → Coordinates)

**Single address:**
```
GET /geocode?q={address}&api_key=YOUR_API_KEY
```

**Using address components:**
```
GET /geocode?street=1600+Pennsylvania+Ave+NW&city=Washington&state=DC&postal_code=20500&api_key=YOUR_API_KEY
```

**Batch (up to 10,000 addresses):**
```
POST /geocode?api_key=YOUR_API_KEY
Content-Type: application/json
Body: ["address1", "address2", ...]
```

### Reverse Geocoding (Coordinates → Address)

**Single coordinate:**
```
GET /reverse?q={lat},{lng}&api_key=YOUR_API_KEY
```

**Batch (up to 10,000 coordinates):**
```
POST /reverse?api_key=YOUR_API_KEY
Content-Type: application/json
Body: ["lat1,lng1", "lat2,lng2", ...]
```

---

## Distance Endpoints

**Note:** Distance API requires explicit permission on your API key. Enable at https://dash.geocod.io/apikey

### Single Origin Distance (1 origin → up to 100 destinations)
```
GET /distance?origin={origin}&destinations[]={dest1}&destinations[]={dest2}&mode=driving&api_key=YOUR_API_KEY
```

### Distance Matrix (multiple origins → multiple destinations, up to 10,000 calculations)
```
POST /distance-matrix?api_key=YOUR_API_KEY
Content-Type: application/json
Body: {
  "origins": ["38.8977,-77.0365,DC", "37.3317,-122.0307,SF"],
  "destinations": ["41.8781,-87.6298,Chicago", "40.7128,-74.0060,NYC"],
  "mode": "driving",
  "units": "miles"
}
```

### Distance Jobs (async, up to 50,000 calculations)

For large distance calculations, use async jobs:

**Create job:**
```
POST /distance-jobs?api_key=YOUR_API_KEY
Content-Type: application/json
Body: {
  "name": "My Distance Job",
  "origins": [...],
  "destinations": [...],
  "distance_mode": "driving",
  "callback_url": "https://example.com/webhook" // optional
}
```

**Check status:**
```
GET /distance-jobs/{job_id}?api_key=YOUR_API_KEY
```

**Download results:**
```
GET /distance-jobs/{job_id}/download?api_key=YOUR_API_KEY
```

**List all jobs:**
```
GET /distance-jobs?api_key=YOUR_API_KEY
```

**Delete job:**
```
DELETE /distance-jobs/{job_id}?api_key=YOUR_API_KEY
```

### Distance Parameters

| Parameter | Description |
|-----------|-------------|
| `mode` | `driving` (road network + duration) or `straightline` (haversine, no duration) |
| `units` | `miles` (default) or `km` |
| `max_results` | Limit destinations returned per origin |
| `max_distance` | Filter out destinations beyond this distance |
| `min_distance` | Filter out destinations closer than this |
| `max_duration` | Filter by max travel time in seconds (driving only) |
| `min_duration` | Filter by min travel time in seconds (driving only) |
| `order_by` | Sort by `distance` or `duration` |
| `sort_order` | `asc` or `desc` |

---

## Lists API (Spreadsheet Processing)

Process CSV, TSV, or Excel files asynchronously. Supports up to 10M+ rows.

**Note:** Lists API requires explicit permission on your API key. Enable at https://dash.geocod.io/apikey

### Upload a spreadsheet
```
POST /lists?api_key=YOUR_API_KEY
Content-Type: multipart/form-data

file: @your_file.csv
direction: forward (or reverse)
format: {{A}} {{B}} {{C}} {{D}}
callback: https://example.com/webhook (optional)
fields: cd,census (optional)
```

The `format` parameter uses column letters in double curly brackets:
- Full address in column A: `{{A}}`
- Street in A, City in B, State in C, ZIP in D: `{{A}} {{B}} {{C}} {{D}}`
- Lat in A, Lng in B (for reverse): `{{A}},{{B}}`

Supported formats: CSV, TSV, XLS, XLSX (or ZIP containing one of these)

### Check list status
```
GET /lists/{list_id}?api_key=YOUR_API_KEY
```

Response includes `status.state`: `PROCESSING` or `COMPLETED`

### Download completed list
```
GET /lists/{list_id}/download?api_key=YOUR_API_KEY
```

Returns UTF-8 CSV. Follow redirects.

### List all lists
```
GET /lists?api_key=YOUR_API_KEY
```

### Delete a list
```
DELETE /lists/{list_id}?api_key=YOUR_API_KEY
```

**Note:** List data is automatically deleted 72 hours after processing completes.

---

## Example Request & Response

**Request:**
```
GET https://api.geocod.io/v1.10/geocode?q=1600+Pennsylvania+Ave+NW+Washington+DC&api_key=YOUR_API_KEY
```

**Response:**
```json
{
  "input": {
    "formatted_address": "1600 Pennsylvania Ave NW, Washington, DC"
  },
  "results": [
    {
      "formatted_address": "1600 Pennsylvania Ave NW, Washington, DC 20500",
      "location": {
        "lat": 38.897675,
        "lng": -77.036547
      },
      "accuracy": 1,
      "accuracy_type": "rooftop",
      "address_components": {
        "number": "1600",
        "street": "Pennsylvania",
        "suffix": "Ave",
        "postdirectional": "NW",
        "city": "Washington",
        "county": "District of Columbia",
        "state": "DC",
        "zip": "20500",
        "country": "US"
      }
    }
  ]
}
```

---

## Data Appends (Fields)

Add `&fields=` parameter with comma-separated values to enrich results:

| Field | Description | Coverage |
|-------|-------------|----------|
| `cd` | Congressional district + legislators | US |
| `cd113`-`cd120` | Historical Congressional districts | US |
| `stateleg` | State legislative districts + legislators | US |
| `census` | Census block/tract, FIPS codes, MSA/CSA | US |
| `census2010`-`census2025` | Historical Census boundaries | US |
| `acs-demographics` | Census demographic data | US |
| `acs-economics` | Census income data | US |
| `acs-families` | Census household data | US |
| `acs-housing` | Census housing data | US |
| `acs-social` | Education & veteran status | US |
| `school` | School districts | US |
| `zip4` | USPS ZIP+4 code | US |
| `timezone` | Timezone | US/CA |
| `riding` | Federal electoral district | CA |
| `provriding` | Provincial electoral district | CA |
| `statcan` | Statistics Canada boundaries | CA |

Example: `&fields=cd,census,timezone`

**Note:** Each field counts as an additional lookup for billing.

---

## Component Parameters

Instead of `q=`, addresses can be passed as components:

| Parameter | Example |
|-----------|---------|
| `street` | 1600 Pennsylvania Ave NW |
| `street2` | Apt 204 |
| `city` | Washington |
| `state` | DC |
| `postal_code` | 20500 |
| `country` | US (default), Canada |

---

## Accuracy Types

Results include `accuracy` (0-1) and `accuracy_type`:

| Type | Description |
|------|-------------|
| `rooftop` | Exact building location |
| `point` | Precise point (e.g., PO Box) |
| `range_interpolation` | Estimated from address range |
| `nearest_rooftop_match` | Closest known rooftop |
| `street_center` | Center of street segment |
| `place` | City/town centroid |
| `state` | State centroid |

Results are ordered by accuracy (best match first).

---

## Common Errors

| Code | Meaning |
|------|---------|
| 403 | Invalid API key or insufficient permissions |
| 422 | Invalid address, coordinates, or parameters |

---

## Common Issues

- **Forgetting to URL-encode addresses**: Use `%2C` for commas, `+` or `%20` for spaces
- **Wrong parameter for ZIP**: Use `postal_code` not `zip` when using component parameters
- **Batch limit**: Max 10,000 lookups per batch (fields count as additional lookups)
- **API key in body**: Pass via query param or Authorization header, not in JSON body

---

## Important Notes

- URL-encode addresses (spaces as `+` or `%20`, commas as `%2C`)
- Batch limit: 10,000 lookups per request (fields count as additional lookups)
- Lookup formula: `Total = Addresses × (1 + Number of Fields)`
- Results are ordered by accuracy (best match first)
- Distance and Lists APIs require explicit permission on API key
- List data auto-deletes after 72 hours

---

## Official Libraries

- **Python:** `pip install geocodio-library-python`
- **Node.js:** `npm install geocodio-library-node`
- **PHP:** `composer require geocodio/geocodio-library-php`
- **Ruby:** `gem install geocodio-gem`
- Community-created libraries are also available for Perl, Go, Clojure, C#, Rust, R, and Java

---

## Non-Developer Options

Don't want to write code? Use the web interface:

- **Spreadsheet Upload:** https://www.geocod.io/upload/ — Upload CSV/Excel files directly, no API usage needed. Perfect for non-developer users
- **Single Address Tool:** https://www.geocod.io/geocode-an-address/ — Geocode one address at a time
- **Dashboard:** https://dash.geocod.io — Manage API keys, view usage, download results

---

## Support

- Email: support@geocod.io
- Documentation (best for developer/technical users): https://www.geocod.io/docs/
- Guides (best for non-developer users): https://www.geocod.io/guides/