GROperator

جارٍ التحميل…

English

الأماكن بالاسم

أينما تقبل الواجهة دولة أو مدينة أو حياً، يمكنك إرسال معرّف أو رمز أو اسم بالعربية أو الإنجليزية. وهذا يتيح لموقعك تمرير ما كتبه العميل أو اختاره دون الاحتفاظ بنسخة من فهرس الأماكن. ويعني أيضاً أن الاسم الخاطئ يجب أن يفشل بوضوح وبطريقة مفيدة، وهذا موضوع هذا الدليل.

  • pickup و recipient في POST /shipments، وعنوان recipient في PUT /shipments/{trackingNumber}.
  • pickup و recipient في POST /pricing/quote (الحي اختياري هناك).
  • عنوان التاجر وعناوينه المحفوظة.
  • معاملات الاستعلام country و city و district في نقاط الجغرافيا، وفلتر city في GET /shipments.
المستوى ما يمكنك إرساله
الدولة المعرّف، أو رمز ISO من حرفين (SA، لا فرق بين الصغير والكبير)، أو الاسم العربي أو الإنجليزي. اختيارية حين يكون اسم المدينة غير ملتبس
المدينة المعرّف، أو رمز المدينة (فريد داخل دولته)، أو الاسم العربي أو الإنجليزي
الحي المعرّف، أو رمز الحي، أو الاسم العربي أو الإنجليزي. يُطابَق داخل المدينة التي حُلّت

المعرّف (UUID الذي ترجعه نقاط الجغرافيا) مقبول في كل مستوى وفي كل مكان يُقبل فيه مكان: إنشاء الشحنات وتعديلها وعروض الأسعار وعناوين التاجر وفلاتر القوائم في الجغرافيا والشحنات. والمعرّف يغلب الاسم دائماً. ولا يُنشأ أي شيء من طلب API. إن لم يوجد المكان تحصل على خطأ، لا على سجل جديد.

الاسم الذي ترسله يُوحَّد ثم يُقارن بالأسماء الموحّدة العربية والإنجليزية في الفهرس. المقارنة تطابق تام على الصيغة الموحّدة، فتتطابق اختلافات الإملاء ولا يتطابق إملاء مختلف فعلاً. التوحيد:

  • يتجاهل حالة الأحرف والتشكيل والتطويل؛
  • يوحّد الهمزات أ إ آ إلى ا، وى إلى ي، وة إلى ه، فتجد جده المدينة جدة وتجد مكه المدينة مكة؛
  • يحوّل الأرقام العربية الهندية إلى لاتينية ويحوّل علامات الترقيم إلى مسافات؛
  • يحذف كلمات المكان العامة من أول الاسم أو آخره: حي ومدينة ومنطقة وقرية ومحافظة وdistrict وcity وarea وtown وneighborhood وما شابهها؛
  • يحذف أداة التعريف ال من كل كلمة، وكذلك al أو el المنفصلة.

فكل ما يلي يصل إلى الحي نفسه:

ما ترسله يطابق
حي البرية البرية (يُحذف حي في البداية)
البريه البرية (ة وه سواء)
Al Rawdah و rawdah و AL-RAWDAH الروضة / Al Rawdah
district Olaya العليا / Al Olaya

حدّان يجب معرفتهما: أداة لاتينية ملتصقة (alrawdah) لا تُعرف، والخطأ الإملائي لا يُطابَق (العلايا ليست العليا). لا نخمّن الأخطاء بصمت لأن التخمين الخاطئ قد يرسل الطرد إلى مكان غير مقصود. بدلاً من ذلك تحصل على اقتراحات، كما يلي.

الرد 422 مع أحد الرموز geo_country_not_found أو geo_city_not_found أو geo_district_not_found. ويحمل details كل ما تحتاجه لمساعدة المستخدم:

الحقل المعنى
level country أو city أو district: أي مستوى فشل
input ما أرسلته، لتعرضه للمستخدم
field أي جزء من الطلب فشل: pickup أو recipient أو address أو city
candidates حتى خمسة اقتراحات «هل تقصد» مرتبة من الأفضل، لكل منها id وnameAr وnameEn وscore (من 0 إلى 1) وعند الحاجة parentNameAr وparentNameEn
messageAr الرسالة العربية (توجد حين تكون message إنجليزية)

رد حقيقي لحي مستلم فيه خطأ إملائي:

JSON
{
  "code": "geo_district_not_found",
  "message": "The district was not found in the given city.",
  "status": 422,
  "details": {
    "level": "district",
    "input": "العلايا",
    "candidates": [
      {
        "id": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e91",
        "nameAr": "العليا",
        "nameEn": "Al Olaya",
        "score": 0.8,
        "parentNameAr": null,
        "parentNameEn": null
      }
    ],
    "field": "recipient",
    "messageAr": "لم يتم العثور على الحي في المدينة المحددة."
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

المقترحات هي أقرب الأسماء بتشابه لا يقل عن 0.6 داخل الأب نفسه: أحياء المدينة التي حُلّت. أما المدينة غير الموجودة فتُعطى لها مقترحات حين ترسل country أيضاً (وإلا سيُبحث في العالم كله):

JSON
{
  "code": "geo_city_not_found",
  "message": "The city was not found in the given country.",
  "status": 422,
  "details": {
    "level": "city",
    "input": "جيزان",
    "candidates": [
      {
        "id": "b7c1d2e3-4f50-4a61-8b72-93a4b5c6d7e8",
        "nameAr": "جازان",
        "nameEn": "Jazan",
        "score": 0.8,
        "parentNameAr": null,
        "parentNameEn": null
      }
    ],
    "field": "city",
    "messageAr": "لم يتم العثور على المدينة في الدولة المحددة."
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

إن طابق الاسم أكثر من مكان فلا يُختار لك شيء. تحصل على geo_city_ambiguous أو geo_district_ambiguous. الحالة النموذجية اسم مدينة موجود في دولتين؛ وتحمل المقترحات حينئذ الدولة في parentNameAr وparentNameEn:

JSON
{
  "code": "geo_city_ambiguous",
  "message": "The city name matches more than one city. Specify the country or use the id.",
  "status": 422,
  "details": {
    "level": "city",
    "input": "Springfield",
    "candidates": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "nameAr": "سبرينغفيلد",
        "nameEn": "Springfield",
        "score": 1,
        "parentNameAr": "الولايات المتحدة",
        "parentNameEn": "United States"
      },
      {
        "id": "22222222-2222-4222-8222-222222222222",
        "nameAr": "سبرينغفيلد",
        "nameEn": "Springfield",
        "score": 1,
        "parentNameAr": "أستراليا",
        "parentNameEn": "Australia"
      }
    ],
    "field": "recipient",
    "messageAr": "اسم المدينة يطابق أكثر من مدينة. حدّد الدولة أو استخدم المعرّف."
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

الحل: أرسل country أيضاً، أو أرسل id أحد المقترحات. وحين يطابق اسم المدينة أو الحي عدة سجلات ويكون واحد منها فقط معتمداً، يُستخدم المعتمد ولا يُعدّ الاسم ملتبساً.

الطلب GET /geography/resolve يجري المطابقة نفسها دون إنشاء شيء. أرسل واحداً على الأقل من country وcity وdistrict (والحي يحتاج مدينة). يرجع المعرّفات والاسمين:

GET /geography/resolve
curl -G "https://api.goldrock.live/api/public/v1/geography/resolve" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  --data-urlencode 'country=SA' \
  --data-urlencode 'city=جده' \
  --data-urlencode 'district=حي البرية'
JSON
{
  "country": {
    "id": "5a6f7c1c-1a3e-4c1f-9d5c-3f0d7d2a1b01",
    "nameAr": "المملكة العربية السعودية",
    "nameEn": "Saudi Arabia"
  },
  "city": {
    "id": "a1d3c2b4-0e7f-4f5a-8a62-9c1e2d3b4a05",
    "nameAr": "جدة",
    "nameEn": "Jeddah"
  },
  "district": {
    "id": "e4b7a9d2-6c13-4d8e-b1f0-2a5c7e9f3b18",
    "nameAr": "البرية",
    "nameEn": "Al Bariyah"
  }
}

عند الفشل يرد بأخطاء 422 نفسها أعلاه. استخدم المعرّفات العائدة في طلباتك اللاحقة: فهي غير ملتبسة وتتجاوز المطابقة.

هذه النقاط تحتاج النطاق geography:read وهي مرقّمة (الاصطلاحات):

نقطة النهاية ما ترجعه
GET /geography/countries الدول المفعّلة والمعتمدة
GET /geography/cities?country=SA مدن دولة. تشمل مدن شركتك المعلقة (pending: true)
GET /geography/districts?city=Riyadh&country=SA أحياء مدينة، مع search للتصفية. تشمل أحياءك المعلقة
GET /geography/coverage/cities المدن التي تخدمها شركتك، مع الإشارتين delivery وpickup
GET /geography/coverage?city=Jeddah هل توصّل الشركة إلى مدينة واحدة وتستلم منها
GET /geography/districts
curl -G "https://api.goldrock.live/api/public/v1/geography/districts" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  --data-urlencode 'country=SA' \
  --data-urlencode 'city=Riyadh' \
  --data-urlencode 'search=olaya'

ليست كل مدينة في الفهرس مدينة تخدمها شركتك. يجيب GET /geography/coverage عن مدينة واحدة: delivery صحيحة حين تقع المدينة في منطقة تسعير فعّالة (أو دولتها في منطقة دولية) أو يغطيها فرع فعّال بدور توصيل، وpickup صحيحة حين يغطيها فرع فعّال بدور استلام.

GET /geography/coverage
curl -G "https://api.goldrock.live/api/public/v1/geography/coverage" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  --data-urlencode 'country=SA' \
  --data-urlencode 'city=Jeddah'
JSON
{
  "city": {
    "id": "a1d3c2b4-0e7f-4f5a-8a62-9c1e2d3b4a05",
    "nameAr": "جدة",
    "nameEn": "Jeddah"
  },
  "delivery": true,
  "pickup": false
}

استخدم GET /geography/coverage/cities لملء قائمة المدن بالأماكن التي تخدمها فعلاً:

GET /geography/coverage/cities
curl -G "https://api.goldrock.live/api/public/v1/geography/coverage/cities" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  --data-urlencode 'country=SA' \
  --data-urlencode 'pageSize=100'
  1. حمّل مرة واحدة وخزّن. اجلب coverage/cities لقائمة المدن في نموذجك وخزّنها فترة. واجلب أحياء المدينة عند اختيارها.
  2. فضّل الاختيار على الكتابة. القائمة المنسدلة أو الإكمال التلقائي المغذّى من هذه النقاط لا ينتج أخطاء أسماء، ويمكنك إرسال المعرّفات.
  3. إن سمحت بالكتابة (نص حر أو جداول أو استيراد)، استدعِ GET /geography/resolve حين يفقد الحقل التركيز. عند 422 اعرض details.candidates كأزرار («هل تقصد العليا؟»). وحين يختار المستخدم أحدها احتفظ بـ id.
  4. تحقق من التغطية قبل إظهار زر الطلب: delivery لمدينة المستلم وpickup لمدينة الاستلام. ويبلغك عرض السعر كذلك بـ deliverable.
  5. أرسل المعرّفات متى امتلكتها. إن حللت العنوان سابقاً فأرسل المعرّفات في country وcity وdistrict في الشحنة.
  6. تعامل مع أخطاء geo_* عند الإنشاء أيضاً. قد يتغير الفهرس بين فحصك والطلب. عاملها كفشل تحقق ودع المستخدم يختار من جديد.

وللعناوين في السعودية يلزم أيضاً العنوان الوطني المختصر: أربعة أحرف تتبعها أربعة أرقام، مثل RNBA6769. ويُبلَّغ عن غيابه أو خطأ صيغته على حقله، مثل pickup.shortAddress أو recipient.shortAddress.