Skip to main content
GET
/
v1
/
geocoding
/
places
Find places near a location
curl --request GET \
  --url https://api.footstep.ai/v1/geocoding/places \
  --header 'x-api-key: <api-key>'
import requests

url = "https://api.footstep.ai/v1/geocoding/places"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.footstep.ai/v1/geocoding/places', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.footstep.ai/v1/geocoding/places",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.footstep.ai/v1/geocoding/places"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.footstep.ai/v1/geocoding/places")
  .header("x-api-key", "<api-key>")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.footstep.ai/v1/geocoding/places")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
{
  "results": [
    {
      "coordinates": {
        "lat": 51.5318,
        "lng": -0.1243
      },
      "label": "Caravan, Granary Square, London, England, United Kingdom",
      "name": "Caravan",
      "country": "United Kingdom",
      "country_code": "GBR",
      "region": "England",
      "locality": "London",
      "distance_meters": 120,
      "confidence": 0.92,
      "place_type": "venue"
    }
  ],
  "query": {
    "query": "coffee shop",
    "near": {
      "lat": 51.5322,
      "lon": -0.124
    },
    "radius": 5,
    "size": 10
  }
}
{
  "error": "<string>",
  "message": "<string>"
}
{
  "error": "<string>",
  "message": "<string>"
}

Authorizations

x-api-key
string
header
required

Your Footstep API key

Query Parameters

query
string
required

What to search for (e.g. 'coffee shop', 'restaurant', 'supermarket', 'train station', 'park')

near
string

Place name to search near (e.g. 'Kings Cross, London'). Geocoded internally. Provide either near OR both near.lat and near.lon, not both.

near.lat
number

Latitude of search center. Prefer this over near whenever you already have coordinates — viewport centre, last-known location, a prior result. Pair with near.lon.

Required range: -90 <= x <= 90
near.lon
number

Longitude of search center. Pair with near.lat.

Required range: -180 <= x <= 180
radius
number
default:5

Search radius in kilometres

Required range: 0.1 <= x <= 50
size
integer
default:5

Maximum number of results. Ask for more only when you genuinely want a longer candidate list

Required range: 1 <= x <= 40
boundary.country
string

Comma-separated ISO 3166-1 alpha-3 country codes to restrict results (e.g. 'GBR' or 'GBR,USA'). Set when the search context is country-bound.

Response

Places matching the query

results
object[]
required
query
object
required