Skip to main content
Privacy-first 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. Built entirely on open data (OpenStreetMap, Who’s on First, OpenAddresses, and GeoNames) with no user tracking.

​
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"
No configuration, no setup, no SDK required. Every result includes a confidence score (0-1) and the data source it came from, so you always know how reliable a match is and where the data originated.

​
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,
  "layer": "venue",
  "source": "openstreetmap"
}
FieldWhat it tells you
coordinatesWGS 84 latitude and longitude
labelPre-formatted display string
confidence0 to 1. How well this result matched your query
layerWhat type of place this is (see below)
sourceWhich dataset this result came from

​
Layers

Filter results by type using the layers parameter:
LayerDescriptionExample
venueNamed places: businesses, landmarks, parksBuckingham Palace
addressStreet addresses10 Downing Street
streetStreet names without house numbersOxford Street
neighbourhoodNeighbourhoods and suburbsShoreditch
localityCities and townsLondon
countyCounties and districtsGreater London
regionStates, provinces, regionsEngland
countryCountriesUnited Kingdom

​
Data sources

All data is open and auditable. No proprietary black box.
SourceWhat it provides
OpenStreetMapVenues, addresses, streets, and place boundaries worldwide
Who’s on FirstAdministrative boundaries (cities, regions, countries) with stable identifiers
OpenAddressesMachine-readable street addresses from authoritative government sources
GeoNamesGlobal gazetteer of populated places and geographic features

​
Endpoints

EndpointDescription
GET /searchText to coordinates. Search for any address, place, or landmark
GET /structured-searchText to coordinates. Search by address components (street, city, postcode)
GET /reverseCoordinates to address. Find what’s at a given lat/lng
GET /autocompleteTypeahead suggestions as the user types
POST /batchGeocode up to 1,000 addresses in a single request
GET /parseBreak a free-text address into structured components

​
When to use which

You want to…Use
Build a search box with suggestionsAutocomplete
Geocode a known addressSearch
Geocode address fields from a databaseStructured search
Find what’s at a map pinReverse
Process a spreadsheet of addressesBatch
Clean messy address data before geocodingParse → 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.