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

# Introduction

> Geocoding for addresses, places, and coordinates

<Frame>
  <img src="https://mintcdn.com/footstep/QNknRZ9DgHsEJ89b/images/geocoding.webp?fit=max&auto=format&n=QNknRZ9DgHsEJ89b&q=85&s=fdae8ad7c578ab8704ee5bb3e8dc6617" alt="Geocoding" width="1408" height="768" data-path="images/geocoding.webp" />
</Frame>

## Footstep Geocoding API

The Geocoding API converts between text and coordinates. Search for an address and get back coordinates, or send coordinates and get back an address.

### Design philosophy

Every request is one line. Send text, get coordinates:

```bash theme={null}
curl "https://api.footstep.ai/v1/geocoding/search?text=Buckingham+Palace" \
  -H "x-api-key: sk_live_your_key_here"
```

Every result includes a confidence score (0-1), so you always know how reliable a match is.

### Response conventions

Every geocoding result uses the same shape:

```json theme={null}
{
  "coordinates": { "lat": 51.5014, "lng": -0.1419 },
  "label": "Buckingham Palace, London, England, United Kingdom",
  "name": "Buckingham Palace",
  "country": "United Kingdom",
  "country_code": "GBR",
  "region": "England",
  "locality": "London",
  "confidence": 0.95,
  "place_type": "venue"
}
```

| Field | What it tells you |
| - | - |
| `coordinates` | WGS 84 latitude and longitude |
| `label` | Pre-formatted display string |
| `confidence` | 0 to 1. How well this result matched your query |
| `place_type` | What type of place this is (see below) |

### Place Types

Filter results by type using the `place_types` parameter:

| Place Type | Description | Example |
| - | - | - |
| `venue` | Named places: businesses, landmarks, parks | Buckingham Palace |
| `address` | Street addresses | 10 Downing Street |
| `street` | Street names without house numbers | Oxford Street |
| `neighbourhood` | Neighbourhoods and suburbs | Shoreditch |
| `locality` | Cities and towns | London |
| `county` | Counties and districts | Greater London |
| `region` | States, provinces, regions | England |
| `country` | Countries | United Kingdom |

### Endpoints

| Endpoint | Description |
| - | - |
| [`GET /search`](/api/endpoint/search) | Text to coordinates. Search for any address, place, or landmark |
| [`GET /structured-search`](/api/endpoint/structured-search) | Text to coordinates. Search by address components (street, city, postcode) |
| [`GET /reverse`](/api/endpoint/reverse) | Coordinates to address. Find what's at a given lat/lng |
| [`GET /autocomplete`](/api/endpoint/autocomplete) | Typeahead suggestions as the user types |
| [`POST /batch`](/api/endpoint/batch) | Geocode up to 1,000 addresses in a single request |
| [`GET /parse`](/api/endpoint/parse) | Break a free-text address into structured components |

### When to use which

| You want to... | Use |
| - | - |
| Build a search box with suggestions | [Autocomplete](/api/endpoint/autocomplete) |
| Geocode a known address | [Search](/api/endpoint/search) |
| Geocode address fields from a database | [Structured search](/api/endpoint/structured-search) |
| Find what's at a map pin | [Reverse](/api/endpoint/reverse) |
| Process a spreadsheet of addresses | [Batch](/api/endpoint/batch) |
| Clean messy address data before geocoding | [Parse](/api/endpoint/parse) → [Structured search](/api/endpoint/structured-search) |

### Focus and boundary

Two shared parameters work across search and autocomplete:

**`focus.point`** biases results towards a location without excluding distant matches. Useful when "Springfield" should prefer the one near your user, not the largest one globally.

```
/v1/geocoding/search?text=Springfield&focus.point.lat=39.78&focus.point.lon=-89.65
```

**`boundary.country`** restricts results to one or more countries. Pass ISO 3166-1 alpha-3 codes:

```
/v1/geocoding/search?text=London&boundary.country=GBR
```

### Authentication

All endpoints require an API key passed via the `x-api-key` header. See the [authentication guide](/authentication) for details.


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