API v3 — نشط

توثيق واجهة برمجة التطبيقات CKAN

يمكنك الوصول إلى البيانات المفتوحة عبر بوابة النقل من خلال واجهة REST. ابحث، فلتر، وادمج مجموعات البيانات في تطبيقاتك.


نظرة عامة

واجهة CKAN Action API v3 — واجهة REST كاملة

نسخة API
v3
Action API (stable)
الصيغة
JSON
الطلبات والإجابات
طرق
GET / POST
قراءة وكتابة
مصادقة
Token
Header Authorization
BASE URL 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"
200 OK — نوع الإجابة
{
  "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) لمجموعات البيانات على البوابة

GET /api/3/action/package_list

يعرض قائمة بجميع أسماء مجموعات البيانات المتاحة على البوابة.

المعاملنوعالوصف
limit optintالحد الأقصى لعدد النتائج
offset optintإزاحة الترقيم
GET /api/3/action/package_show?id={id}

يعيد البيانات الوصفية الكاملة لمجموعة البيانات، بما في ذلك الموارد، العلامات، والمؤسسة.

المعاملنوعالوصف
id مطلوبstringاسم أو UUID لمجموعة البيانات
POST /api/3/action/package_search

البحث في مجموعات البيانات باستخدام محرك Solr الذي يدعم الفلاتر، والfacets، والفرز.

المعاملنوعالوصف
q optstringطلب البحث (صيغة Solr)
fq optstringفلتر query (ex: organization:transport)
sort optstringالفرز (ex: name asc)
rows optintعدد النتائج (الافتراضي: 10)
start optintإزاحة الصفحات (Offset de pagination)
facet.field optlistالحقول للfacets
POST /api/3/action/package_create

إنشاء مجموعة بيانات جديدة. يتطلب توكن المصادقة.

المعاملنوعالوصف
name مطلوبstringمعرّف فريد (slug، أحرف صغيرة)
title optstringعنوان قابل للقراءة
owner_org optstringمعرّف المنظمة المالكة
notes optstringالوصف (يدعم Markdown)

الموارد

الملفات وURLs المرفقة بمجموعة البيانات

GET /api/3/action/resource_show?id={id}

إرجاع البيانات الوصفية الخاصة بالمورد (URL، format، الحجم، تاريخ التعديل).

المعاملنوعالوصف
id مطلوبstringUUID للمورد
GET /api/3/action/resource_search?query={field:term}

البحث عن الموارد حسب الحقل. (ex: format:CSV, name:horaires)

المعاملنوعالوصف
query مطلوبstringالبحث بصيغة champ:valeur
limit optintالحد الأقصى لعدد النتائج

مخزن البيانات API

طلبات منظمة على البيانات الجدولية

يسمح مخزن البيانات بالاستعلام مباشرة عن بيانات CSV/XLS المحمّلة في CKAN، مع الفلاتر، الفرز، وحتى طلبات SQL كاملة.

POST /api/3/action/datastore_search

البحث في بيانات مورد من مخزن البيانات. يدعم البحث full-text، الفلاتر حسب الحقول، وتقسيم الصفحات.

المعاملنوعالوصف
resource_id مطلوبstringUUID للمورد
q optstringبحث full-text في جميع الحقول
filters optobjectالفلاتر حسب الحقل : {"ville": "Tunis"}
limit optintعدد النتائج (الافتراضي: 100)
offset optintإزاحة للصفحات (Offset pour pagination)
sort optstringالفرز (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"
    })
});
POST /api/3/action/datastore_search_sql

تنفيذ استعلامات SQL للقراءة فقط (SELECT) على بيانات مخزن البيانات.

المعاملنوعالوصف
sql مطلوبstringاستعلام SQL (SELECT فقط)

فقط استعلامات SELECT مسموحة. يجب أن تكون معرفات الموارد بين علامات اقتباس مزدوجة في SQL.

اختبار API مباشرة

تنفيذ الطلبات من هذه الصفحة

يرجى التحقق من captcha

        


      

رموز الخطأ

فهم استجابات الأخطاء

200
OK نجاح — success: true
400
Bad Request طلب غير صحيح أو معلمات غير صالحة
403
Forbidden Token مفقود أو غير صالح
404
Not Found المورد أو مجموعة البيانات غير موجود
409
Conflict تعارض (الاسم موجود بالفعل)
500
Server Error خطأ داخلي في الخادم

تنبيه : CKAN يرجع دائما HTTP 200 حتى في حالة خطأ منطقي. هذا الحقل "success": false الذي يشير إلى الفشل. رموز HTTP 400/403/409/500 تظهر فقط للأخطاء الصياغية الحرجة. تحقق من ذلك دائما الحقل success في كل استجابة.

مثال على استجابة خطأ :

{
  "help": "...",
  "success": false,
  "error": {
    "__type": "Authorization Error",
    "message": "Access denied"
  }
}

التوثيق الرسمي لـ CKAN

الموارد الكاملة والمراجع

CKAN v2.11 — التوثيق عبر الإنترنت

يمكنك العثور على المرجع الكامل لـ API Action، دليل DataStore، وجميع الوظائف المتاحة.

دليل 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 →