الأماكن بالاسم
أينما تقبل الواجهة دولة أو مدينة أو حياً، يمكنك إرسال معرّف أو رمز أو اسم بالعربية أو الإنجليزية. وهذا يتيح لموقعك تمرير ما كتبه العميل أو اختاره دون الاحتفاظ بنسخة من فهرس الأماكن. ويعني أيضاً أن الاسم الخاطئ يجب أن يفشل بوضوح وبطريقة مفيدة، وهذا موضوع هذا الدليل.
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 إنجليزية) |
رد حقيقي لحي مستلم فيه خطأ إملائي:
{
"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 أيضاً (وإلا سيُبحث في العالم كله):
{
"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:
{
"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 (والحي يحتاج مدينة). يرجع المعرّفات والاسمين:
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=حي البرية'const params = new URLSearchParams({
"country": "SA",
"city": "جده",
"district": "حي البرية"
});
const response = await fetch(`https://api.goldrock.live/api/public/v1/geography/resolve?${params}`, {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/geography/resolve?' . http_build_query([
'country' => 'SA',
'city' => 'جده',
'district' => 'حي البرية',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/geography/resolve",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
params={
"country": "SA",
"city": "جده",
"district": "حي البرية",
},
timeout=30,
)
print(response.status_code, response.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 |
هل توصّل الشركة إلى مدينة واحدة وتستلم منها |
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'const params = new URLSearchParams({
"country": "SA",
"city": "Riyadh",
"search": "olaya"
});
const response = await fetch(`https://api.goldrock.live/api/public/v1/geography/districts?${params}`, {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/geography/districts?' . http_build_query([
'country' => 'SA',
'city' => 'Riyadh',
'search' => 'olaya',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/geography/districts",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
params={
"country": "SA",
"city": "Riyadh",
"search": "olaya",
},
timeout=30,
)
print(response.status_code, response.json())ليست كل مدينة في الفهرس مدينة تخدمها شركتك. يجيب GET /geography/coverage عن مدينة واحدة: delivery صحيحة حين تقع المدينة في منطقة تسعير فعّالة (أو دولتها في منطقة دولية) أو يغطيها فرع فعّال بدور توصيل، وpickup صحيحة حين يغطيها فرع فعّال بدور استلام.
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'const params = new URLSearchParams({
"country": "SA",
"city": "Jeddah"
});
const response = await fetch(`https://api.goldrock.live/api/public/v1/geography/coverage?${params}`, {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/geography/coverage?' . http_build_query([
'country' => 'SA',
'city' => 'Jeddah',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/geography/coverage",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
params={
"country": "SA",
"city": "Jeddah",
},
timeout=30,
)
print(response.status_code, response.json()){
"city": {
"id": "a1d3c2b4-0e7f-4f5a-8a62-9c1e2d3b4a05",
"nameAr": "جدة",
"nameEn": "Jeddah"
},
"delivery": true,
"pickup": false
}استخدم 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'const params = new URLSearchParams({
"country": "SA",
"pageSize": "100"
});
const response = await fetch(`https://api.goldrock.live/api/public/v1/geography/coverage/cities?${params}`, {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/geography/coverage/cities?' . http_build_query([
'country' => 'SA',
'pageSize' => '100',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/geography/coverage/cities",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
params={
"country": "SA",
"pageSize": "100",
},
timeout=30,
)
print(response.status_code, response.json())- حمّل مرة واحدة وخزّن. اجلب
coverage/citiesلقائمة المدن في نموذجك وخزّنها فترة. واجلب أحياء المدينة عند اختيارها. - فضّل الاختيار على الكتابة. القائمة المنسدلة أو الإكمال التلقائي المغذّى من هذه النقاط لا ينتج أخطاء أسماء، ويمكنك إرسال المعرّفات.
- إن سمحت بالكتابة (نص حر أو جداول أو استيراد)، استدعِ
GET /geography/resolveحين يفقد الحقل التركيز. عند422اعرضdetails.candidatesكأزرار («هل تقصد العليا؟»). وحين يختار المستخدم أحدها احتفظ بـid. - تحقق من التغطية قبل إظهار زر الطلب:
deliveryلمدينة المستلم وpickupلمدينة الاستلام. ويبلغك عرض السعر كذلك بـdeliverable. - أرسل المعرّفات متى امتلكتها. إن حللت العنوان سابقاً فأرسل المعرّفات في
countryوcityوdistrictفي الشحنة. - تعامل مع أخطاء
geo_*عند الإنشاء أيضاً. قد يتغير الفهرس بين فحصك والطلب. عاملها كفشل تحقق ودع المستخدم يختار من جديد.
وللعناوين في السعودية يلزم أيضاً العنوان الوطني المختصر: أربعة أحرف تتبعها أربعة أرقام، مثل RNBA6769. ويُبلَّغ عن غيابه أو خطأ صيغته على حقله، مثل pickup.shortAddress أو recipient.shortAddress.