API құжаттамасы

HTTPS арқылы REST + JSON. Бір базалық URL, бір кілт, болжамды конверттер.

Базалық URL	`https://nakordoni.eu/api/v1/data/`
Пішім	JSON, UTF-8
Аутентификация	`Authorization: Bearer NKD-DEV-…`
Нұсқалау	Жол бойынша нұсқаланған (v1). Үзіліс тудыратын өзгерістер тек жаңа нұсқамен; v1 жауаптары тұрақты болып қалады.

Осы бетте

Аутентификация · Жауап конверті · Квоталар · Код үлгілері · Өнімдер · Не құруға болады

Аутентификация

Әрбір сұрауға API кілтіңіз Authorization тақырыбында (ұсынылады) немесе ?key= параметрі ретінде қажет.

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

Жауап конверті

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

Қателер ok:false мәнін error.code (missing_api_key, invalid_api_key, qps_exceeded, quota_exceeded, unknown_product, product_unavailable, bad_request, internal_error) және HTTP күй-жайы 401/403/404/429/500 арқылы қайтарады. Жылдамдық шектеу тақырыптары X-Devapi-Limit және X-Devapi-Remaining әрбір есептелетін жауаппен жіберіледі.

Квоталар

	Explorer	Pay As You Grow
стандартты деректер API-ларына күніне шақыру	1,000	50,000
болжам және статистика API-ларына күніне шақыру	200	10,000
QPS	2	20

Күнделікті есептегіштер UTC бойынша түн ортасында қалпына келтіріледі. Сіз квотаның 80% және 100% деңгейінде электрондық хат аласыз.

Код үлгілері

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"])

Өнімдер

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 — квота класы: cheap

Параметр	Сипаттама
`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 — квота класы: heavy

Параметр	Сипаттама
`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 — квота класы: heavy

Параметр	Сипаттама
`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 — квота класы: heavy

Параметр	Сипаттама
`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 — квота класы: cheap

Параметр	Сипаттама
`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 — квота класы: cheap

Параметр	Сипаттама
`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 — квота класы: cheap

Параметр	Сипаттама
`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 — квота класы: cheap

Параметр	Сипаттама
`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 — квота класы: cheap

Параметр	Сипаттама
`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 — квота класы: cheap

Параметр	Сипаттама
`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 Жақында

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

GET https://nakordoni.eu/api/v1/data/weather — квота класы: cheap

Параметр	Сипаттама
`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 — квота класы: cheap

Параметр	Сипаттама
`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 — квота класы: cheap

Параметр	Сипаттама
`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 — квота класы: heavy

Параметр	Сипаттама
`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 Жақында

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 — квота класы: heavy

Параметр	Сипаттама
`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"

Не құруға болады

Дәл сол деректер өнімдері nakordoni.eu сайтындағы визуалдарды көрсетеді — апталық болжам графиктері, сағаттық кезек профильдері, тікелей күй-жай карталары. Болжам және статистика API-ларында не бар екеніне көз жеткізіңіз:

7-day border queue forecast chart built from the Forecast API — Апталық болжам + ең қарбалас күннің сағаттық профилі — Болжам API (prediction_steps=168 / 24)

Hourly queue statistics chart built from the Statistics API — Бекет бойынша сағаттық кезек графигі — Статистика API (stats?ppid=…&compare=1)

Атрибуция

Explorer жоспарының интеграциялары деректер көрсетілетін жерде көрінетін "Data by nakordoni.eu" сілтемесін көрсетуі тиіс. Бұл тегін жоспарды тегін сақтайды.

Тегін API кілтіңізді алыңыз