Query

curl --request POST \
  --url https://api.footstep.ai/v1/ai/query \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "query": "Walking route from Kings Cross to Tower Bridge"
}
'

{
  "intent": "route",
  "parameters": {},
  "result": {},
  "summary": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

POST

query

curl --request POST \
  --url https://api.footstep.ai/v1/ai/query \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "query": "Walking route from Kings Cross to Tower Bridge"
}
'

{
  "intent": "route",
  "parameters": {},
  "result": {},
  "summary": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

Send a natural language query and get back structured geospatial results. The endpoint figures out what you’re asking for (directions, a location, reachability, etc.), resolves any text locations to coordinates, calls the appropriate backend, and returns the full result.

How intent is classified

The endpoint maps queries to the backend that best fits:

Your query sounds like…	Intent	Backend called
”Directions from A to B”	`route`	/v1/routing/route
”Best order to visit these stops”	`optimize`	/v1/routing/optimize
”How far can I walk in 30 minutes”	`isochrone`	/v1/routing/isochrone
”What’s the elevation at…”	`elevation`	/v1/routing/elevation
”Distance between A, B, and C”	`matrix`	/v1/routing/matrix
”Where is…” / “Find…”	`geocode`	/v1/geocoding/search
”What’s at these coordinates”	`reverse_geocode`	/v1/geocoding/reverse

Using context

Pass context.location when your query uses relative terms like “nearest”, “nearby”, or “from here”. Without it, the endpoint can’t resolve those references. Pass context.country to disambiguate place names. “Springfield” with country: "GBR" resolves differently than with country: "USA".

{
  "query": "Walking directions to the nearest park",
  "context": {
    "location": { "lat": 51.5322, "lon": -0.1240 },
    "country": "GBR"
  }
}

Response structure

The response always includes:

Field	What it contains
`intent`	What the query was classified as (`route`, `geocode`, `isochrone`, etc.)
`parameters`	The parameters inferred from the query and passed to the backend
`result`	The full backend response (same schema as calling the endpoint directly)
`summary`	A natural language summary of the result

The result field contains the exact same response you’d get calling the backend endpoint directly. If the intent is route, result contains a RouteResponse. If geocode, it contains a GeocodingSearchResponse. No new schemas to learn.

Error handling

If the query is ambiguous or can’t be resolved:

{
  "error": "ambiguous_query",
  "message": "Could not determine a specific intent from your query.",
  "suggestions": [
    "Try: 'Directions from A to B'",
    "Try: 'Where is [place name]?'",
    "Try: 'How far can I drive in 30 minutes from [location]?'"
  ]
}

If a location in the query can’t be geocoded, the response includes what was resolved and what failed:

{
  "error": "geocode_failed",
  "message": "Could not find a location matching 'the old pub near the river'.",
  "partial": {
    "intent": "route",
    "resolved_locations": [
      { "text": "Kings Cross", "resolved": { "lat": 51.53, "lon": -0.12 } }
    ],
    "unresolved_locations": [
      { "text": "the old pub near the river" }
    ]
  }
}

Authorizations

x-api-key

string

header

required

Your Footstep API key

Body

application/json

query

string

required

Natural language query (e.g. 'Walking route from Kings Cross to Tower Bridge', 'Where is Buckingham Palace?', 'How far can I drive in 30 minutes from Liverpool Street?')

Maximum string length: 1000

context

object

Optional context to improve query understanding

Show child attributes

Response

Structured result from the resolved query

intent

enum<string>

required

Classified intent of the query

Available options:

route,

optimize,

isochrone,

elevation,

matrix,

geocode,

reverse_geocode

parameters

object

required

Parameters inferred from the query and passed to the backend endpoint

result

object

required

Full response from the backend endpoint (RouteResponse, GeocodingSearchResponse, IsochroneResponse, etc.)

summary

string

required

Natural language summary of the result

Routing

Geocoding

Natural Language

Predict

How intent is classified

Using context

Response structure

Error handling

Authorizations

Body

Response

​How intent is classified

​Using context

​Response structure

​Error handling

Authorizations

Body

Response

How intent is classified

Using context

Response structure

Error handling