توثيق واجهة برمجة التطبيقات CKAN
يمكنك الوصول إلى البيانات المفتوحة عبر بوابة النقل من خلال واجهة REST. ابحث، فلتر، وادمج مجموعات البيانات في تطبيقاتك.
نظرة عامة
واجهة CKAN Action API v3 — واجهة REST كاملة
https://catalogue-data.transport.tn/api/3/action/
واجهة CKAN API توفر جميع ميزات بوابة البيانات المفتوحة عبر Endpoints REST. يمكنك سرد مجموعات البيانات، البحث عن الموارد، استعلام مخزن البيانات باستخدام فلاتر SQL، وإدارة المنظمات الخاصة بك بطريقة برمجية.
كل استجابة ترجع كائن JSON يحتوي على ثلاثة مفاتيح:
success, result و help.
البدء السريع
أول طلب API خلال 30 ثانية
ابدأ بسرد جميع مجموعات البيانات المتاحة على البوابة:
# اعرض جميع مجموعات البيانات curl https://catalogue-data.transport.tn/api/3/action/package_list # ابحث باستخدام مصطلح curl https://catalogue-data.transport.tn/api/3/action/package_search \ -d '{"q": "transport", "rows": 5}'
import requests # اعرض جميع مجموعات البيانات response = requests.get( "https://catalogue-data.transport.tn/api/3/action/package_list" ) datasets = response.json()["result"] # البحث في مجموعات بيانات النقل search = requests.post( "https://catalogue-data.transport.tn/api/3/action/package_search", json={"q": "transport", "rows": 5} ) print(search.json()["result"]["results"])
// اعرض جميع مجموعات البيانات const resp = await fetch( "https://catalogue-data.transport.tn/api/3/action/package_list" ); const { result } = await resp.json(); // البحث المتقدم const search = await fetch( "https://catalogue-data.transport.tn/api/3/action/package_search", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ q: "transport", rows: 5 }) });
library(httr2) req <- request("https://catalogue-data.transport.tn/api/3/action/package_list") result <- req %>% req_perform() %>% resp_body_json() print(result$result)
# اعرض جميع مجموعات البيانات $response = Invoke-RestMethod "https://catalogue-data.transport.tn/api/3/action/package_list" $response.result # البحث باستخدام الفلتر $body = @{ q = "transport"; rows = 5 } | ConvertTo-Json $search = Invoke-RestMethod "https://catalogue-data.transport.tn/api/3/action/package_search" ` -Method Post -Body $body -ContentType "application/json"
{
"help": "https://catalogue-data.transport.tn/api/3/action/help_show?name=package_list",
"success": true,
"result": [
"lignes-de-bus-tunis",
"horaires-metro-leger",
"stations-louage-interurbain",
"reseau-train-banlieue-sncft"
]
}
المصادقة
رموز API لعمليات الكتابة
endpoints القراءة (GET) متاحة بدون مصادقة. رمز API Token مطلوب فقط لعمليات الإنشاء أو التعديل أو الحذف.
من CKAN 2.9، تستبدل رموز API المفاتيح القديمة. أنشئ رمزك من ملف التعريف الخاص بك على البوابة.
# تمرير الـ token في رأس Authorization curl https://catalogue-data.transport.tn/api/3/action/package_create \ -H "Authorization: VOTRE_API_TOKEN" \ -d '{"name": "mon-dataset", "title": "Mon jeu de données"}'
import requests API_TOKEN = "votre-token-ici" BASE = "https://catalogue-data.transport.tn/api/3/action" response = requests.post( f"{BASE}/package_create", headers={"Authorization": API_TOKEN}, json={ "name": "mon-dataset", "title": "Mon jeu de données", "owner_org": "transport-tunisie" } )
const API_TOKEN = "votre-token-ici"; const resp = await fetch( "https://catalogue-data.transport.tn/api/3/action/package_create", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": API_TOKEN }, body: JSON.stringify({ name: "mon-dataset", title: "Mon jeu de données" }) });
مجموعات البيانات (Packages)
إدارة كاملة (CRUD) لمجموعات البيانات على البوابة
يعرض قائمة بجميع أسماء مجموعات البيانات المتاحة على البوابة.
| المعامل | نوع | الوصف |
|---|---|---|
limit opt | int | الحد الأقصى لعدد النتائج |
offset opt | int | إزاحة الترقيم |
يعيد البيانات الوصفية الكاملة لمجموعة البيانات، بما في ذلك الموارد، العلامات، والمؤسسة.
| المعامل | نوع | الوصف |
|---|---|---|
id مطلوب | string | اسم أو UUID لمجموعة البيانات |
البحث في مجموعات البيانات باستخدام محرك Solr الذي يدعم الفلاتر، والfacets، والفرز.
| المعامل | نوع | الوصف |
|---|---|---|
q opt | string | طلب البحث (صيغة Solr) |
fq opt | string | فلتر query (ex: organization:transport) |
sort opt | string | الفرز (ex: name asc) |
rows opt | int | عدد النتائج (الافتراضي: 10) |
start opt | int | إزاحة الصفحات (Offset de pagination) |
facet.field opt | list | الحقول للfacets |
إنشاء مجموعة بيانات جديدة. يتطلب توكن المصادقة.
| المعامل | نوع | الوصف |
|---|---|---|
name مطلوب | string | معرّف فريد (slug، أحرف صغيرة) |
title opt | string | عنوان قابل للقراءة |
owner_org opt | string | معرّف المنظمة المالكة |
notes opt | string | الوصف (يدعم Markdown) |
الموارد
الملفات وURLs المرفقة بمجموعة البيانات
إرجاع البيانات الوصفية الخاصة بالمورد (URL، format، الحجم، تاريخ التعديل).
| المعامل | نوع | الوصف |
|---|---|---|
id مطلوب | string | UUID للمورد |
البحث عن الموارد حسب الحقل. (ex: format:CSV, name:horaires)
| المعامل | نوع | الوصف |
|---|---|---|
query مطلوب | string | البحث بصيغة champ:valeur |
limit opt | int | الحد الأقصى لعدد النتائج |
مخزن البيانات API
طلبات منظمة على البيانات الجدولية
يسمح مخزن البيانات بالاستعلام مباشرة عن بيانات CSV/XLS المحمّلة في CKAN، مع الفلاتر، الفرز، وحتى طلبات SQL كاملة.
البحث في بيانات مورد من مخزن البيانات. يدعم البحث full-text، الفلاتر حسب الحقول، وتقسيم الصفحات.
| المعامل | نوع | الوصف |
|---|---|---|
resource_id مطلوب | string | UUID للمورد |
q opt | string | بحث full-text في جميع الحقول |
filters opt | object | الفلاتر حسب الحقل : {"ville": "Tunis"} |
limit opt | int | عدد النتائج (الافتراضي: 100) |
offset opt | int | إزاحة للصفحات (Offset pour pagination) |
sort opt | string | الفرز (ex: "nom asc") |
curl https://catalogue-data.transport.tn/api/3/action/datastore_search \ -H "Authorization: $API_TOKEN" \ -d '{ "resource_id": "RESOURCE_UUID", "limit": 5, "q": "tunis" }'
from ckanapi import RemoteCKAN rc = RemoteCKAN("https://catalogue-data.transport.tn", apikey=API_TOKEN) result = rc.action.datastore_search( resource_id="RESOURCE_UUID", limit=5, q="tunis" ) print(result["records"])
const resp = await fetch( "https://catalogue-data.transport.tn/api/3/action/datastore_search", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": API_TOKEN }, body: JSON.stringify({ resource_id: "RESOURCE_UUID", limit: 5, q: "tunis" }) });
تنفيذ استعلامات SQL للقراءة فقط (SELECT) على بيانات مخزن البيانات.
| المعامل | نوع | الوصف |
|---|---|---|
sql مطلوب | string | استعلام SQL (SELECT فقط) |
فقط استعلامات SELECT مسموحة. يجب أن تكون معرفات الموارد بين علامات اقتباس مزدوجة في SQL.
البحث عبر المتصفح
الوصول المباشر عبر طلبات GET
بعض endpoints يمكن الوصول إليها عبر طلب GET بسيط في المتصفح :
اختبار API مباشرة
تنفيذ الطلبات من هذه الصفحة
رموز الخطأ
فهم استجابات الأخطاء
success: true
تنبيه : CKAN يرجع دائما HTTP 200 حتى في حالة خطأ منطقي. هذا الحقل "success": false الذي يشير إلى الفشل. رموز HTTP 400/403/409/500 تظهر فقط للأخطاء الصياغية الحرجة. تحقق من ذلك دائما الحقل success في كل استجابة.
مثال على استجابة خطأ :
{
"help": "...",
"success": false,
"error": {
"__type": "Authorization Error",
"message": "Access denied"
}
}
التوثيق الرسمي لـ CKAN
الموارد الكاملة والمراجع
دليل API Action
المرجع الكامل لجميع الوظائف: get، create، update، delete، patch.
docs.ckan.org/en/latest/api →DataStore & DataPusher (أداتان لإدارة ونقل البيانات في CKAN)
دليل DataStore للاستعلام عن البيانات المنظمة والاستيراد التلقائي.
DataStore Documentation →ckanapi — Client Python
المكتبة الرسمية Python للتفاعل مع CKAN بطريقة بسيطة وموثوقة.
github.com/ckan/ckanapi →