أهلاً بك زائرنا الكريم، ربما تكون أحد الأعضاء يمكنك تسجيل الدخول أو شرفنا بمشاركتك وقم بالتسجيل

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

تعليمات

  • هذا هو الاطلاق التجريبي للواجهة البرمجية. نرجوا أن تبلغنا اذا واجهت أي مشاكل أو لديك اقتراحات أو تحتاج المساعدة. البريد المخصص للواجهة البرمجية هو api@qaym.com
  • قد تكون هناك تعديلات على الواجهة البرمجية في هذه الفترة. لذلك من الجيد أن تبقى على اطلاع على هذه الصفحة في حال وجود أي تحديثات.
  • الواجهة البرمجية لقيم تعتمد على تعمل على بروتوكول REST, ويتم ارسال الأوامر بنمط GET.
  • يتم جلب جميع النتائج بصيغة JSON, وبترميز UTF-8.
  • العنوان الذي ترسل عليه الأوامر هو : http://api.qaym.com/0.1/
  • تحتاج للحصول على مفتاح للواجهة البرمجية وارساله مع كل أمر بهذه الصيغة:
    <الأمر>/key=<المفتاح>
    فمثلاً اذا كان مفتاحك هو 1234567890, وتريد تنفيذ أمر جلب كل المدن, يكون الأمر كالتالي:
    http://api.qaym.com/0.1/cities/key=1234567890
  • باستخدامك لهذه الواجهة, تعفي قيم من أي مسؤولية تترتب على هذا الاستخدام. وتتعهد بالالتزام باتفاقية الاستخدام التي ستصدر لاحقاً.
  • بامكانك تخزين المعلومات التي تجلبها من الواجهة البرمجية ليوم واحد فقط كحد أعلى. باستخدامك للواجهة والبيانات الناتجة عنها فأنت تتعهد بالالتزام بهذا الشرط.
  • نرجو ألا تثقل على الموقع بأوامر كثيرة في وقت واحد.
  • ابدع واستمتع!


مثال

هذا مثال على استخدام بعض الواجهة البرمجية بلغة PHP. المثال يقوم بجلب قائمة المدن وعرضها
<?php
//عنوان الواجهة البرمجية $service_url = "http://api.qaym.com/0.1/";

// المفتاح
$key = "a9ghbfWHvrdV79k7Qaj";

//أمر جلب المدن
$command = "cities";

//الأمر كاملاً
$resource = $service_url.$command."/key=".$key;

//ارسل الأمر للواجهة البرمجية, لا حاجة لتغيير هذه الأربعة أسطر $curl = curl_init($resource);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$curl_response = curl_exec($curl);
curl_close($curl);

//تحويل نتيجة الأمر من تشفير JSON الى PHP Array $cities = json_decode($curl_response, true);

//عرض النتيجة foreach($cities AS $city)
echo $city['name']. "<br />";
?>


الأوامر

هنا ستجد كل أوامر الواجهة البرمجية وطريقة استخدامها.

الأماكن

هذه هي مجموعة الأوامر المتعلقة بالمدن والدول.

جلب قائمة الدول
أمر يقوم بجلب قائمة الدول الموجودة في الموقع مرتبة أبجدياً

countries

مثال على الأمر:
http://api.qaym.com/0.1/countries/key=1234567890
صيغة الاجابة:
[{"name":<اسم الدولة 1>,"country_id":<رقم الدولة 1>},
{"name":<اسم الدولة 2>,"country_id":<رقم الدولة 2>}]
مثال على الاجابة:
[{"name": "استراليا" ,"country_id":"558"},
{"name":"الإمارات","country_id": "230"},
{"name":"الاردن","country_id": "234"},
...]

جلب معلومات دولة
جلب اسم الدولة, معلومات اضافتها (تاريخ الاضافة ورقم العضو الذي قام باضافتها), واحداثياتها على الخريطة (اذا كان قد تم ادخالها)

countries/<رقم الدولة>

مثال على الأمر:
http://api.qaym.com/0.1/countries/230/key=1234567890
صيغة الاجابة:
{"country_id":"<رقم الدولة>",
"name":"<اسم الدولة>",
"added_by":"<رقم العضو الذي قام باضافة هذه الدولة>",
"addition_timestamp":"<وقت وتاريخ اضافة الدولة>",
"latitude":"<جزء من احداثيات المكان (دوائر العرض)>",
"longitude":"<جزء من احداثيات المكان, (خط الطول)>",
"zoom":"<مقدار قرب الصورة عند استخدام خرائط قوقل>"}
مثال على الاجابة:
{"country_id":"55",
"name":"السعودية",
"added_by":"5",
"addition_timestamp":"2007-07-03 04:17:35",
"latitude":"23.7250117359518",
"longitude":"44.47265625",
"zoom":"4"}

جلب قائمة المدن الموجودة في دولة
قائمة بأسماء ومعلومات كل المدن الموجودة في دولة معينة

countries/<رقم الدولة>/cities

مثال على الأمر:
http://api.qaym.com/0.1/countries/178/cities/key=1234567890
صيغة الاجابة:
[{"city_id":"<رقم المدينة 1>",
"name":"<اسم المدينة 1>",
"added_by":"<رقم العضو الذي قام باضافة هذه المدينة>",
"addition_timestamp":"<وقت وتاريخ اضافة المدينة>",
"latitude":"<جزء من احداثيات المكان (دوائر العرض)>",
"longitude":"<جزء من احداثيات المكان, (خط الطول)>",
"zoom":"<مقدار قرب الصورة عند استخدام خرائط قوقل>"},

{"city_id":"<رقم المدينة 1>",
"name":"<اسم المدينة 1>",
"added_by":"<رقم العضو الذي قام باضافة هذه المدينة>",
"addition_timestamp":"<وقت وتاريخ اضافة المدينة>",
"latitude":"<جزء من احداثيات المكان (دوائر العرض)>",
"longitude":"<جزء من احداثيات المكان, (خط الطول)>",
"zoom":"<مقدار قرب الصورة عند استخدام خرائط قوقل>"},

...
]

جلب قائمة المدن
جلب قائمة بكل المدن الموجودة في الموقع, ومعلوماتها.

cities

مثال على الأمر:
http://api.qaym.com/0.1/cities/key=1234567890
صيغة الاجابة:
[{"city_id":"<رقم المدينة 1>",
"name":"<اسم المدينة 1>",
"added_by":"<رقم العضو الذي قام باضافة هذه المدينة>",
"addition_timestamp":"<وقت وتاريخ اضافة المدينة>",
"latitude":"<جزء من احداثيات المكان (دوائر العرض)>",
"longitude":"<جزء من احداثيات المكان, (خط الطول)>",
"zoom":"<مقدار قرب الصورة عند استخدام خرائط قوقل>"},

{"city_id":"<رقم المدينة 1>",
"name":"<اسم المدينة 1>",
"added_by":"<رقم العضو الذي قام باضافة هذه المدينة>",
"addition_timestamp":"<وقت وتاريخ اضافة المدينة>",
"latitude":"<جزء من احداثيات المكان (دوائر العرض)>",
"longitude":"<جزء من احداثيات المكان, (خط الطول)>",
"zoom":"<مقدار قرب الصورة عند استخدام خرائط قوقل>"},

...
]

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

cities/<رقم المدينة>

مثال على الأمر:
http://api.qaym.com/0.1/cities/231/key=1234567890
صيغة الاجابة:
{"city_id":"<رقم المدينة 1>",
"name":"<اسم المدينة 1>",
"added_by":"<رقم العضو الذي قام باضافة هذه المدينة>",
"addition_timestamp":"<وقت وتاريخ اضافة المدينة>",
"latitude":"<جزء من احداثيات المكان (دوائر العرض)>",
"longitude":"<جزء من احداثيات المكان, (خط الطول)>",
"zoom":"<مقدار قرب الصورة عند استخدام خرائط قوقل>"}

جلب كل المطاعم الموجودة في مدينة

cities/<رقم المدينة>/items

مثال على الأمر:
http://api.qaym.com/0.1/cities/231/items/key=1234567890
صيغة الاجابة:
[{"item_name":"<اسم المطعم 1>","item_id":"<رقم المطعم>"},
{"item_name":"<اسم المطعم 2>","item_id":"<رقم المطعم>"},
{"item_name":"<اسم المطعم 3>","item_id":"<رقم المطعم>"},
...
]
مثال على الاجابة:

جلب قائمة أفضل المطاعم الموجودة في مدينة
جلب قائمة بأفضل 50 مطعم في المدينة.

cities/<رقم المدينة>/items/top

مثال على الأمر:
http://api.qaym.com/0.1/cities/231/items/top/key=1234567890
صيغة الاجابة:
[{"item_id":"<رقم المطعم>",
"item_name":"<اسم المطعم>",
"score":"<علامات المطعم>",
"weighted_score":"<العلامة الموزونة للمطعم, المعيار الأفضل لمقارنة الجودة بين المطاعم>",
"ratio":"<متوسط الأصوات للمطعم>",
"tags":
{"<رقم الوصف 1>":"<الوصف 1>",
"<رقم الوصف 2>":"<الوصف 2>"
},
"total_number_of_votes":"<عدد أصوات الأعضاء للمطعم>",
"number_of_positive_votes":"<عدد الأعضاء الذين أعجبهم المطعم>",
"number_of_negative_votes":"<عدد الأعضاء الذين لم يعجبهم المطعم>"},
...]

المطاعم

جلب معلومات مطعم
جلب معلومات مطعم معين.

items/<رقم المطعم>

مثال على الأمر:
http://api.qaym.com/0.1/items/57/key=1234567890
صيغة الاجابة:
{"item_id":"<رقم المطعم>",
"item_name":"<اسم المطعم>",
"url":"<رابط موقع المطعم>",
"score":"<علامات المطعم>",
"vote_count":"<عدد أصوات الأعضاء للمطعم>",
"ratio":"<متوسط الأصوات للمطعم>",
"weighted_score":"<العلامة الموزونة للمطعم, المعيار الأفضل لمقارنة الجودة بين المطاعم>",
"username":"<اسم العضو الذي أضاف المطعم>",
"user_id":"<رقم العضو الذي أضاف المطعم>"}

جلب معلومات فروع مطعم

items/<رقم المطعم>/locations

مثال على الأمر:
http://api.qaym.com/0.1/items/57/locations/key=1234567890
صيغة الاجابة:
[{"country":"<اسم الدولة>",
"city":"<اسم المدينة>",
"location_id":"<رقم الفرع>",
"score":"<نتيجة تصويت الأعضاء على صحة معلومات الفرع>",
"address":"<عنوان الفرع (وصف مكانه)>",
"user_id":"<رقم العضو الذي حرر اخر نسخة من معلومات فرع المطعم",
"latitude":"<جزء من احداثيات المكان (دوائر العرض)>",
"longitude":"<جزء من احداثيات المكان, (خط الطول)>",
"title":"<اسم الفرع>",
"phone":<رقم هاتف الفرع>,
"tiny_thumb_file_detail_id":"2102",
"username":"<اسم المستخدم الذي حرر اخر نسخة من معلومات فرع المطعم>",
"city_id":"<رقم المدينة التي يقع فيها الفرع>",
"country_id":"<رقم الدولة التي يقع فيها الفرع>"},
...]

جلب تقييمات مطعم
جلب كل التقييمات التي كتبها الأعضاء عن مطعم معين.

items/<رقم المطعم>/reviews

مثال على الأمر:
http://api.qaym.com/0.1/items/57/reviews/key=1234567890
صيغة الاجابة:
[{ "username":"<اسم كاتب التقييم>",
"title":"<عنوان التقييم>",
"user_id":"<رقم كاتب المستخدم>",
"score":"<عدد الأعضاء الذين وجدوا هذا التقييم مفيد>",
"time":"<وقت كتابة التقييم. بصيغة مكتوبة، مثل: "قبل ثلاث ساعات وعشرين دقيقة">",
"number_of_posts":"<عدد التعليقات على التقييم>",
"last_poster_id":"<رقم اخر شخص علق على التقييم>",
"last_post_time":"<وقت كتابة اخر تقييم. بصيغة مكتوبة>",
"text":"<نص التقييم>",
"last_edit_user_id":"<رقم اخر مستخدم قام بتحرير التقييم>",
"last_edit_time":"<وقت اخر تحرير للتقييم.بصيغة مكتوبة>"},
...]

جلب صور مطعم

items/<رقم المطعم>/images

مثال على الأمر:
http://api.qaym.com/0.1/items/57/images/key=1234567890
صيغة الاجابة:
[{"user_id":"<رقم العضو الذي قام برفع الصورة>",
"file_detail_id":"<رقم الصورة*>",
"title":"<عنوان الصورة>",
"username":"<اسم العضو الذي قام برفع الصورة>"},
...]

//note: * رابط الصورة يتم تكوينه باستخدام هذا الرقم. مثلاً الصورة رقم 400 رابطها يبدو بهذا الشكل:
http://www.qaym.com/400.jpg

جلب تصوياتات الأعضاء على مطعم

items/<رقم المطعم>/votes

مثال على الأمر:
http://api.qaym.com/0.1/items/57/votes/key=1234567890
صيغة الاجابة:
{"up":
[{"vote":"<الصوت: 1 او -1>",
"user_id":"<رقم العضو صاحب الصوت>",
"username":"<اسم العضو صاحب الصوت>"},
{"vote":"<الصوت: 1 او -1>",
"user_id":"<رقم العضو صاحب الصوت>",
"username":"<اسم العضو صاحب الصوت>"}],

"down":
[{"vote":"<الصوت: 1 او -1>",
"user_id":"<رقم العضو صاحب الصوت>",
"username":"<اسم العضو صاحب الصوت>"},
{"vote":"<الصوت: 1 او -1>",
"user_id":"<رقم العضو صاحب الصوت>",
"username":"<اسم العضو صاحب الصوت>"}]
}

الأوصاف

جلب قائمة الأوصاف

tags

مثال على الأمر:
http://api.qaym.com/0.1/tags/key=1234567890
صيغة الاجابة:
[{"tag":"<الوصف 1>",
"tag_def_id":"<رقم الوصف 1>"},

{"tag":"<الوصف 2>",
"tag_def_id":"<رقم الوصف 2>"},

{"tag":"<الوصف 3>",
"tag_def_id":"<رقم الوصف 3>"}
...]

جلب المطاعم الموصوفة بوصف معين
جلب قائمة بكل المطعم المموصوفة بوصف معين.

tags/<رقم الوصف>/items

مثال على الأمر:
http://api.qaym.com/0.1/tags/157/items/key=1234567890
صيغة الاجابة:
[{"item_id":"<رقم المطعم 1>",
"item_name":"<اسم المطعم 1>"},
{"item_id":"<رقم المطعم 2>",
"item_name":"<اسم المطعم 2>"},
...]