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, რომ 20-მდე გამშვები პუნქტი ერთი მოთხოვნით წაიკითხოთ ციკლის ნაცვლად.

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.

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

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

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

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

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

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

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 გეგმაში ატრიბუციის არარსებობა ან დეინდექსაცია ჯერ შეხსენებას, შემდეგ გასაღების შეჩერებას იწვევს. Pay As You Grow კლიენტებს ატრიბუცია არ მოეთხოვებათ.

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