API Documentation

REST + JSON over HTTPS. One base URL, one key, predictable envelopes.

Base URL	`https://nakordoni.eu/api/v1/data/`
Format	JSON, UTF-8
Auth	`Authorization: Bearer NKD-DEV-…`
Versioning	Path-versioned (v1). Breaking changes only with a new version; v1 responses stay stable.

Authentication

Every request needs your API key in the Authorization header (recommended) or as a ?key= parameter.

curl "https://nakordoni.eu/api/v1/data/queue?ppid=id_13" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Response envelope

{
  "ok": true,
  "api_version": "v1",
  "product": "queue",
  "attribution": "Data by nakordoni.eu",
  "data": { ... },
  "usage": { "limit": 1000, "used": 42, "reset": "2026-06-06T00:00:00Z" }
}

Errors return ok:false with error.code (missing_api_key, invalid_api_key, qps_exceeded, quota_exceeded, unknown_product, product_unavailable, bad_request, internal_error) and HTTP status 401/403/404/429/500. Rate-limit headers X-Devapi-Limit and X-Devapi-Remaining are sent on every metered response.

Quotas

	Explorer	Pay As You Grow
calls/day on standard data APIs	1,000	50,000
calls/day on forecast & statistics APIs	200	10,000
QPS	2	20

Daily counters reset at midnight UTC. You get an email at 80% and 100% of quota.

Code samples

curl

curl "https://nakordoni.eu/api/v1/data/queue?ppid=id_13" \
  -H "Authorization: Bearer $NKD_API_KEY"

JavaScript (fetch)

const res = await fetch('https://nakordoni.eu/api/v1/data/forecast?ppid=id_13&prediction_steps=24', {
  headers: { Authorization: `Bearer ${process.env.NKD_API_KEY}` }
});
const { ok, data, usage } = await res.json();
if (!ok) throw new Error(data?.error?.code ?? res.status);
console.log(`forecast points: ${data.length}, calls left today: ${usage.limit - usage.used}`);

Python (requests)

import os, requests

r = requests.get(
    "https://nakordoni.eu/api/v1/data/stats",
    params={"ppid": "id_15", "compare": 1},
    headers={"Authorization": f"Bearer {os.environ['NKD_API_KEY']}"},
    timeout=15,
)
payload = r.json()
print(payload["data"]["daily"], payload["usage"])

Products

Checkpoints Directory API

Directory of all monitored border checkpoints: IDs, names, countries, coordinates and status. Use it to discover ppid values for the other APIs.

GET https://nakordoni.eu/api/v1/data/checkpoints — quota class: cheap

Parameter	Description
`country`	Filter by numeric country code (1=UA, 2=PL, 3=SK, 4=HU, 5=RO, 6=MD, 7=BY, 8=LT, 9=LV, …)
`lang`	Language for checkpoint names (default en)

curl "https://nakordoni.eu/api/v1/data/checkpoints" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Live Border Queue API

Real-time queue length, wait estimate and status for any monitored checkpoint, plus hourly/daily aggregates.

GET https://nakordoni.eu/api/v1/data/queue — quota class: heavy

Parameter	Description
`ppid`	Checkpoint ID, e.g. id_13 (see /api/v1/data/checkpoints)
`section`	Data section (optional)
`origin`	Origin country code (optional)
`destination`	Destination country code (optional)

curl "https://nakordoni.eu/api/v1/data/queue?ppid=id_13" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Checkpoint Hourly Statistics API

Hourly historical queue stats per checkpoint and date: 24 hourly values, daily avg/min/max, peak and quietest hours, day-over-day comparison.

GET https://nakordoni.eu/api/v1/data/stats — quota class: heavy

Parameter	Description
`ppid`	Checkpoint ID
`date`	YYYY-MM-DD (default: yesterday)
`compare`	1 = include previous day + delta
`lang`	Language code (default uk)

curl "https://nakordoni.eu/api/v1/data/stats?ppid=id_15&date=2026-06-01&compare=1" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Queue Forecast API

ML ensemble forecast of queue levels: 24-hour and 7-day (168h) horizons with confidence bounds. The same model that powers nakordoni.eu predictions.

GET https://nakordoni.eu/api/v1/data/forecast — quota class: heavy

Parameter	Description
`ppid`	Checkpoint ID
`prediction_steps`	24 (default) or 168 for 7-day

curl "https://nakordoni.eu/api/v1/data/forecast?ppid=id_13&prediction_steps=24" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Checkpoint Alternatives API

Nearby alternative checkpoints on the same border with current queues and distance deltas.

GET https://nakordoni.eu/api/v1/data/alternatives — quota class: cheap

Parameter	Description
`ppid`	Checkpoint ID
`lang`	Language code

curl "https://nakordoni.eu/api/v1/data/alternatives?ppid=id_13" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Data Freshness API

When a checkpoint was last updated, by which source, and a freshness rating.

GET https://nakordoni.eu/api/v1/data/update-info — quota class: cheap

Parameter	Description
`ppid`	Checkpoint ID
`lang`	Language code

curl "https://nakordoni.eu/api/v1/data/update-info?ppid=id_13" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

EU Fuel Prices API

Average petrol/diesel/LPG prices across EU countries plus nearest stations, aggregated from official national sources.

GET https://nakordoni.eu/api/v1/data/fuel — quota class: cheap

Parameter	Description
`country`	ISO country code (optional)
`lat`	Latitude (optional)
`lon`	Longitude (optional)
`lang`	Language code

curl "https://nakordoni.eu/api/v1/data/fuel?country=PL" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Driver POIs API

Truck parkings (14k+), free showers, services and supermarkets across Europe with coordinates.

GET https://nakordoni.eu/api/v1/data/pois — quota class: cheap

Parameter	Description
`type`	parking\|shower\|supermarket\|industrial
`lat`	Latitude
`lon`	Longitude
`radius`	Radius km

curl "https://nakordoni.eu/api/v1/data/pois?type=parking&lat=50.7&lon=23.9&radius=50" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Truck Driving Bans API

European truck driving restrictions by country and date, including seasonal and holiday bans.

GET https://nakordoni.eu/api/v1/data/truck-bans — quota class: cheap

Parameter	Description
`country`	ISO country code (optional)
`date`	YYYY-MM-DD (optional)

curl "https://nakordoni.eu/api/v1/data/truck-bans?country=PL" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Trading Sundays API

Sunday retail-opening regulations and upcoming trading Sundays per regulated EU country.

GET https://nakordoni.eu/api/v1/data/trading-sundays — quota class: cheap

Parameter	Description
`country`	ISO country code (optional)

curl "https://nakordoni.eu/api/v1/data/trading-sundays?country=PL" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Border Weather API Coming soon

Current conditions and road warnings at border checkpoints. (Coming soon)

GET https://nakordoni.eu/api/v1/data/weather — quota class: cheap

Parameter	Description
`ppid`	Checkpoint ID

curl "https://nakordoni.eu/api/v1/data/weather?ppid=id_13" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Bus Carrier Border Stats API

Border-crossing performance per bus carrier: crossings, average/median/min/max wait minutes — built from our own plate-matched crossing records.

GET https://nakordoni.eu/api/v1/data/bus-carriers — quota class: cheap

Parameter	Description
`ppid`	Checkpoint ID or "all" for aggregated
`days`	Period 1-90 (default 30)
`min_crossings`	Minimum crossings to include a carrier (default 3)
`limit`	Max carriers returned (default 20)

curl "https://nakordoni.eu/api/v1/data/bus-carriers?ppid=all&days=30" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Road Conditions API

Approved road condition reports near borders and on major corridors: potholes, roadworks, closures, ice, hazards — combining driver reports with automatic accelerometer detections from our navigation app.

GET https://nakordoni.eu/api/v1/data/road-conditions — quota class: cheap

Parameter	Description
`country`	ISO country code (optional)
`condition_type`	pothole\|speed_bump\|roadwork\|closure\|hazard\|ice\|… (optional)
`severity`	low\|moderate\|major\|critical (optional)
`lat`	Latitude (optional)
`lng`	Longitude (optional)
`radius`	Radius km (default 50)
`limit`	Max results (default 100, cap 500)

curl "https://nakordoni.eu/api/v1/data/road-conditions?country=UA&severity=major" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Border AI Assistant API

Ask our production AI assistant any border-crossing question (queues, forecasts, rules, fuel, routes) and get the same grounded answer that powers the nakordoni.eu widget — in 24 languages. Already used in production by yaknakordoni.com.ua.

GET https://nakordoni.eu/api/v1/data/assistant — quota class: heavy

Parameter	Description
`q`	The question (plain text)
`lang`	Answer language (default en)
`ppid`	Checkpoint context, e.g. id_13 (optional)

curl "https://nakordoni.eu/api/v1/data/assistant?q=How long is the queue at Krakovets now?&lang=en&ppid=id_13" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Road Quality API Coming soon

Road roughness scores per corridor computed from anonymized accelerometer telemetry of real drives: roughness index 0-100, pothole density per km, rough-corridor clusters with coordinates. (Coming soon)

GET https://nakordoni.eu/api/v1/data/road-quality — quota class: heavy

Parameter	Description
`bbox`	Bounding box
`corridor`	Route corridor

curl "https://nakordoni.eu/api/v1/data/road-quality?bbox=22.5,48.2,24.5,50.5" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

What you can build

The same data products render the visuals on nakordoni.eu — weekly forecast charts, hourly queue profiles, live status cards. A taste of what the forecast and stats APIs contain:

7-day border queue forecast chart built from the Forecast API — Weekly forecast + busiest-day hourly profile — Forecast API (prediction_steps=168 / 24)

Hourly queue statistics chart built from the Statistics API — Per-checkpoint hourly queue chart — Statistics API (stats?ppid=…&compare=1)

Attribution

Explorer-plan integrations must show a visible "Data by nakordoni.eu" link wherever the data is displayed. It keeps the free plan free.

Get your free API key