@footstep/api-spec

OpenAPI 3.1 specification and TypeScript schema validator for the Footstep geospatial API — geocoding, routing, isochrones, elevation, places, and predictive search.

• API docs: docs.footstep.ai
• API base URL: https://api.footstep.ai
• Sign up: footstep.ai

Install

npm install @footstep/api-spec
# or
pnpm add @footstep/api-spec

Usage

Code generation

Most consumers will want the raw OpenAPI document for use with code generators (openapi-typescript, openapi-generator, orval, etc.):

import spec from "@footstep/api-spec/openapi.json";

npx openapi-typescript node_modules/@footstep/api-spec/openapi.json -o src/footstep.d.ts

Runtime response validation

The package also ships a small Ajv-based validator for asserting that responses match a named component schema. Useful in tests:

import { validateSchema } from "@footstep/api-spec";

const response = await fetch("https://api.footstep.ai/v1/geocoding/search?text=...", {
  headers: { "x-api-key": process.env.FOOTSTEP_API_KEY! },
});
validateSchema("GeocodingSearchResponse", await response.json());

validateSchema throws on failure with a descriptive message listing every violation. List available schemas with getSchemaNames().

What's in the spec

Endpoints covered by the OpenAPI document:

• Geocoding — /v1/geocoding/search, /places, /autocomplete, /reverse, /structured-search, /batch, /parse, /resolve
• Routing — /v1/routing/route, /matrix, /isochrone, /elevation, /optimize, /compare, /locate, /snap, /find-and-route, /search-along-route
• AI — /v1/ai/parse-address, /v1/ai/query
• Predict — /v1/predict

Full request/response schemas, parameter docs, and worked examples for every endpoint live in the API reference.

Versioning

This package follows semantic versioning tied to the API surface:

• Patch — documentation tweaks, no shape changes
• Minor — additive changes (new endpoints, optional parameters, additional response fields)
• Major — breaking changes (removed endpoints, required parameter additions, response shape changes)

The runtime API at api.footstep.ai always serves the latest contract. Pin to a specific version of this package if you want predictable code generation.

License

MIT