> ## 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.