API დოკუმენტაცია

ავტენტიფიკაცია

ყველა მოთხოვნას სჭირდება თქვენი 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 იგზავნება ყველა გაზომილ პასუხზე.

კვოტები

დღიური მთვლელები ნულდება შუაღამისას 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, error, usage } = await res.json();
if (!ok) throw new Error(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"])

Excel (Power Query)

მიიღეთ საზღვრის რიგების, პროგნოზისა თუ სატვირთოების შეზღუდვების მონაცემები პირდაპირ ცხრილში Power Query-ის ჩაშენებული JSON კონექტორის საშუალებით — კოდის გარეშე, განრიგით განახლებადი. იგივე Headers სქემა მუშაობს API-ის ნებისმიერი პროდუქტისთვის — საკმარისია მხოლოდ URL-ის შეცვლა.

Data → Get Data → From Other Sources → Blank Query, then Home → Advanced Editor and paste:

let
    ApiKey = "NKD-DEV-XXXX-XXXX-XXXX",
    Source = Json.Document(Web.Contents("https://nakordoni.eu/api/v1/data/queue",
        [Query = [ppid = "id_13"], Headers = [Authorization = "Bearer " & ApiKey]])),
    data = Source[data],
    AsTable = Record.ToTable(data)
in
    AsTable

შეინახეთ API გასაღები M-მოთხოვნის შიგნით (Home → Advanced Editor), და არა ფურცლის უჯრედში — Power Query ბლოკავს ვებ-მოთხოვნას, რომელიც აგებულია სხვა მოთხოვნიდან ან უჯრედიდან ("Formula.Firewall"), თუ კონფიდენციალურობის დონე არ არის დაყენებული როგორც Organizational.

რამდენიმე გამშვები პუნქტი ერთ ცხრილში (ავტოპარკის დაფები) — e.g. every truck crossing UA→EU (crossing_type=9):

let
    ApiKey = "NKD-DEV-XXXX-XXXX-XXXX",
    Source = Json.Document(Web.Contents("https://nakordoni.eu/api/v1/data/border/1/all/9",
        [Headers = [Authorization = "Bearer " & ApiKey]])),
    checkpoints = Source[data],
    AsTable = Table.FromRecords(checkpoints)
in
    AsTable

Data → Refresh All Excel-ში ან დაგეგმილი განახლება Power BI / Excel Online-ში ინახავს მონაცემებს განახლებულს — გამოკითხვის (polling) კოდის გარეშე.

ERP ინტეგრაცია (BAS / BAF და 1C-ოჯახის პლატფორმები)

BAS / BAF და 1C-ოჯახის სხვა პლატფორმებს შეუძლიათ ამ API-ს გამოძახება პირდაპირ დაგეგმილი დავალებიდან — HTTPConnection და ReadJSON, შუალედური სერვისის გარეშე. ყველაზე გავრცელებული სცენარია ევროკავშირის საწვავის ფასების საინფორმაციო რეგისტრის განახლება.

საინფორმაციო რეგისტრის განახლება (საწვავის ფასები, ყველა ქვეყანა ერთი მოთხოვნით)

// Scheduled job — runs once a day
Connection = New HTTPConnection("nakordoni.eu", 443, , , , 30, New OpenSSLSecureConnection);

Headers = New Map;
Headers.Insert("Authorization", "Bearer NKD-DEV-XXXX-XXXX-XXXX");

Request  = New HTTPRequest("/api/v1/data/fuel", Headers);
Response = Connection.Get(Request);

Reader = New JSONReader;
Reader.SetString(Response.GetBodyAsString("UTF-8"));
Answer = ReadJSON(Reader, True);
Reader.Close();

If Answer["ok"] <> True Then
    // Answer["error"]["code"] says why; Answer["usage"] holds your quota state
    Return;
EndIf;

For Each Row In Answer["data"] Do
    Record = InformationRegisters.FuelPrices.CreateRecordManager();
    Record.Period   = CurrentSessionDate();
    Record.Country  = Row["country"];    // "PL", "DE", "SK", "RO", ...
    Record.Diesel   = Row["diesel"];
    Record.Petrol   = Row["petrol"];
    Record.LPG      = Row["lpg"];
    Record.Currency = Row["currency"];
    Record.Write();
EndDo;

სამი რამ უნდა გააკეთოთ სწორად: გადაეცით New OpenSSLSecureConnection 443 პორტზე, თორემ მოთხოვნა TLS-ზე ჩავარდება; გამოიძახეთ /api/v1/data/fuel country პარამეტრის გარეშე, რომ ერთმა მოთხოვნამ ყველა ქვეყანა დააბრუნოს ცალკეული გამოძახებების ნაცვლად; და შეამოწმეთ ok, სანამ data-ს შეეხებით — შეცდომები ბრუნდება როგორც ok:false და error.code, და არა როგორც გამონაკლისი. მაგალითში გამოყენებულია პლატფორმის ინგლისური საკვანძო სიტყვები; ლოკალიზებული ეკვივალენტები (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) იდენტურად მუშაობს.

საწვავის ფასები წყაროებში დღეში ერთხელ იცვლება, ამიტომ დღეში ერთი ან ორი დაგეგმილი დავალება საკმარისია და უფასო Explorer კვოტის ფარგლებში რჩება. რიგების ცოცხალი მონაცემები (queue, multi, border) რამდენიმე წუთში ერთხელ იცვლება — მათ საკუთარი გრაფიკით მიმართეთ და გამოიყენეთ multi, რომ 5-მდე გამშვები პუნქტი ერთი მოთხოვნით წაიკითხოთ ციკლის ნაცვლად.

MCP სერვერი

გირჩევნიათ ხელსაწყოების გამოძახება REST-ის ნაცვლად? ჩვენ ვმართავთ ნამდვილ MCP სერვერს (Streamable HTTP ტრანსპორტი), რომელიც აძლევს წვდომას ამ API-ის უსაფრთხო, მხოლოდ წაკითხვადი ქვეჯგუფზე, როგორც MCP ხელსაწყოებზე — იგივე API გასაღები, იგივე კვოტა, უბრალოდ განსხვავებული ტრანსპორტი.

Endpoint: https://nakordoni.eu/mcp · Server card: /.well-known/mcp/server-card.json

get_api_status      — no key required
list_checkpoints     — country, lang
get_border_queue     — origin, destination, crossing_type, lang
get_live_queue       — ppid, lang
get_queue_forecast   — ppid, prediction_steps

კლიენტის კონფიგურაცია (Claude Desktop / Claude Code):

{
  "mcpServers": {
    "nakordoni": {
      "url": "https://nakordoni.eu/mcp",
      "headers": { "Authorization": "Bearer NKD-DEV-XXXX-XXXX-XXXX" }
    }
  }
}

პროდუქტები

აირჩიეთ ენდპოინტი, რომ ნახოთ სრული ცნობარი, პარამეტრები, ვერსიები და ცოცხალი Sandbox.

სტანდარტული გამოიყენებს სტანდარტულ მონაცემთა კვოტას  ·  მძიმე გამოიყენება პროგნოზისა და სტატისტიკის კვოტა — იხილეთ კვოტები

სასაზღვრო რიგები

პროგნოზები და სტატისტიკა

საწვავი და ლოკაციები

მოგზაურობის დაგეგმვა

მძღოლები და გზები

Your Fleet (NakBus Live)

AI ასისტენტი

ისტორიული მონაცემების ექსპორტი

დამტკიცებულ დეველოპერებს შეუძლიათ ჩამოტვირთონ საათობრივად გასაშუალოებული, გამოქვეყნებული სასაზღვრო რიგების ისტორია 5-მდე საგუშაგოსთვის (მოძრავი ფანჯარა 90 დღემდე) gzip-CSV, NDJSON ან JSON ფორმატში. ეს პორტალის ფუნქციაა და არა API ენდპოინტი; ექსპორტს თქვენს ანგარიშში, ჩანართში „მონაცემთა ექსპორტი“ ქმნით და იქიდანვე იწერთ.

წვდომა გაიცემა მოთხოვნით: გახსენით Data ტიპის მიმართვა და მიუთითეთ, რომელი საგუშაგოები გჭირდებათ, დროის რომელი მონაკვეთი და რისთვის იყენებთ. დამტკიცების შემდეგ თქვენს ანგარიშში გამოჩნდება ჩანართი „მონაცემთა ექსპორტი“. ნაგულისხმევი ლიმიტი: 1 ექსპორტი დღეში, თითოში 5-მდე საგუშაგო — გაზრდა მოგვთხოვეთ.

ველები — თითო მწკრივი თითო საგუშაგოსა და თითო UTC საათზე

ექსპორტში ხვდება მხოლოდ გამოქვეყნებული მონაცემები, რომლებიც გადის ჩვენს ანომალიებისა და ხარისხის შემოწმებას (ნედლი ერთეული ჩანაწერების გარეშე). ყველა დროის ნიშნული UTC-შია. ფაილები ინახება 10 დღე.

წარმომავლობა: ყოველი ფაილის სათაურში ჩაშენებულია ხელმოწერილი ანაბეჭდი (sha256 + HMAC), ასე რომ ნებისმიერი ასლის შესახებ მოგვიანებითაც შეიძლება დადასტურდეს, რომ ის ნამდვილი nakordoni.eu-ს მონაცემია და შემოწმდეს ცვლილებებზე — ჩამოტვირთვის შემდეგაც კი.

# sha256: 3f9c…   # signature: e87b…
ppid,checkpoint_name,hour_utc,direction,vehicle_type,avg_queue_length,avg_wait_minutes,sample_count
id_10,Hrushiv,2026-06-12T02:00:00Z,UA->PL,car,11,,4

რის შექმნა შეგიძლიათ

იგივე მონაცემთა პროდუქტები ქმნის ვიზუალებს nakordoni.eu-ზე — ყოველკვირეული პროგნოზის გრაფიკები, საათობრივი რიგების პროფილები, ცოცხალი სტატუსის ბარათები. გემო იმისა, რასაც პროგნოზისა და სტატისტიკის API-ები შეიცავს:

მითითება

Explorer გეგმის ინტეგრაციებმა უნდა აჩვენონ ხილული "Data by nakordoni.eu" ბმული ყველგან, სადაც მონაცემები ჩანს. ეს ინარჩუნებს უფასო გეგმას უფასოდ.

ზუსტი კოდი

დააკოპირეთ ეს ფრაგმენტი უცვლელად. ბმული უნდა დარჩეს ინდექსირებადი: ჩვეულებრივი HTML <a href>, რომელსაც საძიებო სისტემები მიჰყვებიან — არ დაამატოთ rel="nofollow" ან rel="sponsored", არ გამოსახოთ მხოლოდ JavaScript-ით და არ დამალოთ CSS-ით.

<a href="https://nakordoni.eu/" title="Border queues, forecasts &amp; statistics">Data by nakordoni.eu</a>

კომპაქტური წვრილი ვარიანტი (მაგ., გრაფიკის ან ვიჯეტის ქვეშ):

<p style="font-size:12px;margin:4px 0">
  Data by <a href="https://nakordoni.eu/">nakordoni.eu</a>
</p>

შეგიძლიათ მიუთითოთ თქვენი ენის ვერსიაზე, მაგ. https://nakordoni.eu/ka/ — ითვლება ნებისმიერი ინდექსირებადი ბმული nakordoni.eu-ზე. ანკორის ტექსტი "Data by nakordoni.eu" უნდა დარჩეს ინგლისურად.

სად განვათავსოთ

• უშუალოდ მონაცემთა ბლოკის გვერდით ან ქვეშ (ცხრილი, გრაფიკი, ვიჯეტი, პასუხი) — იმავე ეკრანზე, ხილული დამატებითი დაწკაპუნების გარეშე.
• ყველა გვერდზე ან აპის ეკრანზე, სადაც ჩვენი მონაცემები ჩანს — არა მხოლოდ "ჩვენ შესახებ" გვერდზე.
• წაკითხვადი ზომა და კონტრასტი: მინიმუმ ~11px, არ არის დამალული, არ არის ჩაკეცილი, არა ფონის ფერში.
• ნატიური მობილური აპები HTML ბმულების გარეშე: აჩვენეთ ტექსტი "Data by nakordoni.eu" მონაცემთა ეკრანზე და დააწკაპუნებადი ბმული განათავსეთ ინფორმაციის ეკრანზე.

პერიოდულად ვამოწმებთ ატრიბუციას რეგისტრაციისას მითითებულ "მონაცემთა გამოყენების გვერდზე". უფასო Explorer გეგმაში ატრიბუციის არარსებობა ან დეინდექსაცია ჯერ შეხსენებას, შემდეგ გასაღების შეჩერებას იწვევს. ფასიანი გეგმის მქონე კლიენტებს ატრიბუცია არ მოეთხოვებათ.

მონაცემების ლიცენზია და ბაზრები

Your API key grants a licence to use our data in the countries you declared when you signed up, and only in those countries. We review every declaration before granting full access, because our data is our own product and we do not license it into markets without knowing where it will be published.

• Declare every country your site, app or product serves. You can change the list from your dashboard at any time; a change puts your account back into review.
• Until your markets are approved your key runs on reduced limits - half of the Starter plan allowance. This applies whatever plan you are on.
• ჩვენ შეგვიძლია მხოლოდ ზოგიერთი ქვეყანა დავამტკიცოთ, რომელიც თქვენ მოითხოვეთ. დამტკიცებული სია, არა მოთხოვნილი, განსაზღვრავს ქვეყნებს, რომლებსაც pokრავს თქვენი ლიცენზია.
• Publishing or redistributing our data in a market you did not declare, or reselling it as a competing data feed, is a breach of these terms and can suspend your key without notice.
• Some plans are offered only in selected regions. Availability depends on the markets you declare.

მონაცემების აქტუალობა

მონაცემების სიახლე დამოკიდებულია თქვენს ტარიფზე. თავად პასუხში ნიშანი არ არის — ყველა ტარიფი აბრუნებს იმავე ველებს, იმავე ტიპებს და პასუხის იმავე სტრუქტურას.

• ფასიანი ტარიფები — Student, Starter, Pro და Pro MAX: ცოცხალი ტელემეტრია, დაყოვნების გარეშე.
• უფასო ტარიფი Explorer: სნეპშოტი ბოლო 15–30 წუთიდან. ზუსტი სხვაობა მოთხოვნიდან მოთხოვნამდე იცვლება.

დაყოვნებული პასუხი არასოდეს არის შეცდომა და არც ლიმიტის პრობლემა — ეს არის სრულფასოვანი, ვალიდური პასუხი უფრო ძველი რიცხვებით. მოთხოვნის გამეორება უფრო ახალ მონაცემებს არ დააბრუნებს.

თუ თქვენს აპლიკაციას სჭირდება აქტუალური მონაცემები, ნებისმიერი ფასიანი ტარიფი აბრუნებს ტელემეტრიას რეალურ დროში.

მიიღეთ თქვენი უფასო API გასაღები