API documentation

01

Quickstart

Send your key as a Bearer token. Start with capabilities: it lists your countries, operations and plan limits.

export NILQ_API_KEY=nilq_sk_...
curl -s https://nilq.com/api/v1/capabilities \
  -H "Authorization: Bearer $NILQ_API_KEY"

curl -s https://nilq.com/api/v1/places/search \
  -H "Authorization: Bearer $NILQ_API_KEY" -H "Content-Type: application/json" \
  -d '{"country_code": "ES", "latitude": 36.5101, "longitude": -4.8824,
       "radius_meters": 1000, "limit": 10, "category_filters": []}'

Keys are delivered privately and never belong in URLs, public code or browsers. Every response carries an X-Request-ID; you may send your own UUID in that header to correlate logs.

02

Endpoints

Call	What it does	Usage
`GET /capabilities`	Your countries, operations, versions and plan limits	Not counted
`GET /usage`	This month's lookups, bulk records and saved addresses, used and remaining	Not counted
`GET /places/categories`	Published place categories for a country	Not counted
`POST /places/search`	Places near a coordinate, by category or name	1 lookup
`GET /places/{id}?country_code=ES`	One place by its source id, e.g. `foursquare:4abc`	1 lookup
`POST /places/analyze`	Count, nearest and travel-time nearest for chosen categories	1 lookup
`POST /stays/search`	Hotels, apartments and campsites near a coordinate	1 lookup
`GET /stays/{id}?country_code=ES`	One stay by its source id	1 lookup
`POST /geocode/forward`, `/geocode/reverse`	Address to coordinates and back, with honest resolution and postcode	1 lookup
`POST /locations/climate`	Monthly 2020-2025 climate facts for a coordinate	1 lookup
`POST /locations/enrich`	Location context signals for a coordinate	1 lookup
`POST /routes`, `/matrix`, `/isochrones`	Walk, bike and drive routes, matrices and travel-time areas	1 lookup per call
`POST /jobs` and `/jobs/{id}`	Bulk enrichment, place analysis or address geocoding	1 lookup per successful record
`/catalogue/...`	Saved locations, saved analyses and their answers	Saved address slots; refreshes are not counted
`POST /mcp`	The same operations for AI assistants over MCP	As the REST call

The full schema is at GET /openapi.json (needs the schema:read scope). Only successful calls count; failed, rejected and timed-out calls are not charged.

03

Examples

Analyse a location

POST /api/v1/places/analyze
{"country_code": "PT", "location": {"latitude": 38.7101, "longitude": -9.1374},
 "radius_meters": 800, "category_ids": ["foursquare:4bf58dd8d48988d1e0931735"],
 "metrics": ["count", "geometric_nearest", "travel_time_nearest"], "mode": "walk"}

Route

POST /api/v1/routes
{"country_code": "ES", "mode": "bike",
 "origin": {"latitude": 36.5101, "longitude": -4.8824},
 "destination": {"latitude": 36.5141, "longitude": -4.8784}}

Bulk job

curl -s https://nilq.com/api/v1/jobs \
  -H "Authorization: Bearer $NILQ_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-batch-2026-10-01" \
  -d '{"operation": "location_enrichment", "records": [
        {"reference_id": "unit-17", "country_code": "ES", "latitude": 36.51, "longitude": -4.88}]}'
# then poll GET /api/v1/jobs/{id} until "succeeded" and read /api/v1/jobs/{id}/results (NDJSON)

A job takes up to 100 records; result files are kept for 24 hours. Repeating a request with the same Idempotency-Key returns the same job and is not charged twice.

04

MCP for AI assistants

Connect any MCP client that can send an Authorization header, for example Claude Code:

claude mcp add --transport http nilq https://nilq.com/api/v1/mcp \
  --header "Authorization: Bearer $NILQ_API_KEY"

Tools cover capabilities, usage, categories, place and stay search and detail, analysis, geocoding, climate, routing, bulk jobs and the saved catalogue. MCP calls share your plan limits and usage with REST. Location text you pass is treated as data, never as instructions.

05

Errors

Errors use application/problem+json with a stable code:

{"type": "about:blank", "title": "Too Many Requests", "status": 429,
 "code": "throttled", "detail": "..."}

400 invalid input, 401 missing or invalid key, 403 scope or country not included.
404 not published for this country, 409 conflict (for example a saved address limit).
413 async_required: the calculation is too large to answer directly (more than 50 route candidates); submit it as a bulk job, which routes up to 500 candidates per location.
429 rate or monthly limit reached, 503 a service is temporarily unavailable. Retry with backoff.

06

Limits and data

Request rate and monthly lookups follow your plan and apply to your whole organization, across keys and MCP. The rate is counted per second; a client paced at its plan rate is never refused for timing jitter.
GET /usage shows lookups used and remaining this month and when the count resets.
Routes, matrices and isochrones cover mainland Spain and Portugal, the Balearic and Canary Islands, Madeira and the Azores. Ceuta and Melilla have places, stays and addresses, but no routing yet: those calls answer out_of_coverage.
Travel-time analysis answers at once for up to 49 route candidates. A denser area answers 413 async_required; run it as a bulk job, which routes up to 500.
Search radius up to 25 km and up to 100 results per page; responses say when a result list may be incomplete.
Answers carry the data versions they were computed on. Saved answers show whether they are current or stale.
Show the attributions listed on the data sources page where you display results.

Use is governed by the Terms of Service. Questions: api@nilq.com.