Footstep Geocoding

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:

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:

{
  "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`	Text to coordinates. Search for any address, place, or landmark
`GET /structured-search`	Text to coordinates. Search by address components (street, city, postcode)
`GET /reverse`	Coordinates to address. Find what’s at a given lat/lng
`GET /autocomplete`	Typeahead suggestions as the user types
`POST /batch`	Geocode up to 1,000 addresses in a single request
`GET /parse`	Break a free-text address into structured components

When to use which

You want to…	Use
Build a search box with suggestions	Autocomplete
Geocode a known address	Search
Geocode address fields from a database	Structured search
Find what’s at a map pin	Reverse
Process a spreadsheet of addresses	Batch
Clean messy address data before geocoding	Parse → 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 for details.

Documentation Index