GROperator

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

English

Geography

كل عمليات واجهة LastMile العامة، مولَّدة من وثيقة OpenAPI. نص المرجع بالإنجليزية في اللغتين.

GET

/api/public/v1/geography/cities

#

List cities, optionally of one country

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: geography:read

Active approved cities plus your company's own pending cities (pending: true). Paginated; scope geography:read.

المعاملات

الاسمالموضعالنوعالوصف
countryquerystring

Optional country: id, ISO code (e.g. SA) or name in Arabic or English.

pagequeryinteger (int32)
الافتراضي: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
الافتراضي: 25

Items per page, 1 to 100 (larger values are clamped to 100).

searchquerystring

Optional text matched against the Arabic name, English name and city code.

مثال طلب

GET /geography/cities
curl "https://api.goldrock.live/api/public/v1/geography/cities" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200A page of cities.

الاستجابات · الحقل
الحقلالنوعالوصف
itemsarray<PublicCityDto>يقبل null

Items of the requested page.

id
items[].id
string (uuid)

City id.

nameAr
items[].nameAr
stringيقبل null

Arabic name.

nameEn
items[].nameEn
stringيقبل null

English name.

code
items[].code
stringيقبل null

City code (unique within its country), when defined.

countryId
items[].countryId
string (uuid)

Id of the country the city belongs to.

pending
items[].pending
boolean

True for a city created by your company that the platform has not approved yet.

pageinteger (int32)

Current page number, starting at 1.

pageSizeinteger (int32)

Requested page size (1 to 100, default 25).

totalCountinteger (int32)

Total number of items across all pages.

totalPagesinteger (int32)

Total number of pages.

200 · مثال استجابة
{
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1
}
الحالةالوصف
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

422

The country could not be resolved (geo_country_not_found).

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

GET

/api/public/v1/geography/countries

#

List countries

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: geography:read

Only active, approved countries. Paginated; scope geography:read.

المعاملات

الاسمالموضعالنوعالوصف
pagequeryinteger (int32)
الافتراضي: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
الافتراضي: 25

Items per page, 1 to 100 (larger values are clamped to 100).

searchquerystring

Optional text matched against the Arabic name, English name and ISO code.

مثال طلب

GET /geography/countries
curl "https://api.goldrock.live/api/public/v1/geography/countries" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200A page of countries.

الاستجابات · الحقل
الحقلالنوعالوصف
itemsarray<PublicCountryDto>يقبل null

Items of the requested page.

id
items[].id
string (uuid)

Country id.

nameAr
items[].nameAr
stringيقبل null

Arabic name.

nameEn
items[].nameEn
stringيقبل null

English name.

code
items[].code
stringيقبل null

ISO 3166-1 alpha-2 code.

pageinteger (int32)

Current page number, starting at 1.

pageSizeinteger (int32)

Requested page size (1 to 100, default 25).

totalCountinteger (int32)

Total number of items across all pages.

totalPagesinteger (int32)

Total number of pages.

200 · مثال استجابة
{
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1
}
الحالةالوصف
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

Forbidden

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

GET

/api/public/v1/geography/coverage

#

Does the company deliver to / pick up from a city?

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: geography:read

Delivery is true when the city is in an active pricing zone (or its country in an international zone) or covered by an active branch with a delivery role; pickup when an active branch covers it with a pickup role. Scope geography:read.

المعاملات

الاسمالموضعالنوعالوصف
countryquerystring

Optional country (id, ISO code or name); narrows an ambiguous city name.

cityquerystring

Required city: id, code or name.

مثال طلب

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'

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200Coverage of the city.

الاستجابات · الحقل
الحقلالنوعالوصف
cityPublicGeoNodeDto

A resolved geography node (id and both names).

id
city.id
string (uuid)

Resolved id.

nameAr
city.nameAr
stringيقبل null

Arabic name.

nameEn
city.nameEn
stringيقبل null

English name.

deliveryboolean

True when the company delivers to the city.

pickupboolean

True when the company picks up from the city.

200 · مثال استجابة
{
  "city": {
    "id": "a1d3c2b4-0e7f-4f5a-8a62-9c1e2d3b4a05",
    "nameAr": "جدة",
    "nameEn": "Jeddah"
  },
  "delivery": true,
  "pickup": false
}
الحالةالوصف
400

city is missing.

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

422

Country or city could not be resolved.

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

GET

/api/public/v1/geography/coverage/cities

#

List the cities the company covers

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: geography:read

Active approved cities with delivery and pickup flags. Paginated; scope geography:read.

المعاملات

الاسمالموضعالنوعالوصف
countryquerystring

Optional country filter (id, ISO code or name).

pagequeryinteger (int32)
الافتراضي: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
الافتراضي: 25

Items per page, 1 to 100 (larger values are clamped to 100).

searchquerystring

Optional text matched against names and city code.

مثال طلب

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'

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200A page of covered cities.

الاستجابات · الحقل
الحقلالنوعالوصف
itemsarray<PublicCoveredCityDto>يقبل null

Items of the requested page.

id
items[].id
string (uuid)

City id.

nameAr
items[].nameAr
stringيقبل null

Arabic name.

nameEn
items[].nameEn
stringيقبل null

English name.

code
items[].code
stringيقبل null

City code, when defined.

countryId
items[].countryId
string (uuid)

Country id.

delivery
items[].delivery
boolean

True when the company delivers to the city.

pickup
items[].pickup
boolean

True when the company picks up from the city.

pageinteger (int32)

Current page number, starting at 1.

pageSizeinteger (int32)

Requested page size (1 to 100, default 25).

totalCountinteger (int32)

Total number of items across all pages.

totalPagesinteger (int32)

Total number of pages.

200 · مثال استجابة
{
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1
}
الحالةالوصف
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

422

The country could not be resolved.

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

GET

/api/public/v1/geography/districts

#

List the districts of a city

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: geography:read

Active approved districts plus your company's own pending districts (pending: true). Paginated; scope geography:read.

المعاملات

الاسمالموضعالنوعالوصف
countryquerystring

Optional country (id, ISO code or name); narrows an ambiguous city name.

cityquerystring

Required city: id, code or name in Arabic or English.

pagequeryinteger (int32)
الافتراضي: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
الافتراضي: 25

Items per page, 1 to 100 (larger values are clamped to 100).

searchquerystring

Optional text matched against the Arabic name, English name and district code.

مثال طلب

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'

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200A page of districts.

الاستجابات · الحقل
الحقلالنوعالوصف
itemsarray<PublicDistrictDto>يقبل null

Items of the requested page.

id
items[].id
string (uuid)

District id.

nameAr
items[].nameAr
stringيقبل null

Arabic name.

nameEn
items[].nameEn
stringيقبل null

English name.

code
items[].code
stringيقبل null

District code, when defined.

cityId
items[].cityId
string (uuid)

Id of the city the district belongs to.

pending
items[].pending
boolean

True for a district created by your company that the platform has not approved yet.

pageinteger (int32)

Current page number, starting at 1.

pageSizeinteger (int32)

Requested page size (1 to 100, default 25).

totalCountinteger (int32)

Total number of items across all pages.

totalPagesinteger (int32)

Total number of pages.

200 · مثال استجابة
{
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1
}
الحالةالوصف
400

city is missing (validation_failed).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

422

Country or city could not be resolved (geo_* codes with candidates).

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

GET

/api/public/v1/geography/resolve

#

Validate a location by names (or ids/codes) before creating a shipment

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: geography:read

Returns the resolved ids and names. Nothing is ever created. When a level cannot be matched, the response is 422 with code geo_country_not_found, geo_city_not_found, geo_district_not_found, geo_city_ambiguous or geo_district_ambiguous and details = { level, input, candidates[] } with "did you mean" suggestions. At least one parameter is required; a district requires a city. Scope geography:read.

المعاملات

الاسمالموضعالنوعالوصف
countryquerystring

Country: id, ISO code or name.

cityquerystring

City: id, code or name.

districtquerystring

District: id, code or name.

مثال طلب

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=Riyadh' \
  --data-urlencode 'district=Al Olaya'

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200The resolved location.

الاستجابات · الحقل
الحقلالنوعالوصف
countryPublicGeoNodeDto

A resolved geography node (id and both names).

id
country.id
string (uuid)

Resolved id.

nameAr
country.nameAr
stringيقبل null

Arabic name.

nameEn
country.nameEn
stringيقبل null

English name.

cityPublicGeoNodeDto

A resolved geography node (id and both names).

id
city.id
string (uuid)

Resolved id.

nameAr
city.nameAr
stringيقبل null

Arabic name.

nameEn
city.nameEn
stringيقبل null

English name.

districtPublicGeoNodeDto

A resolved geography node (id and both names).

id
district.id
string (uuid)

Resolved id.

nameAr
district.nameAr
stringيقبل null

Arabic name.

nameEn
district.nameEn
stringيقبل null

English name.

200 · مثال استجابة
{
  "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"
  }
}
الحالةالوصف
400

No parameter was given.

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

422

The location could not be resolved.

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء