GROperator

Geography

Every operation of the LastMile Public API, generated from the OpenAPI document. The reference text is in English in both languages.

GET

/api/public/v1/geography/cities

#

List cities, optionally of one country

API key + secret, or bearer tokenRequired scope: geography:read

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

Parameters

NameInTypeDescription
countryquerystring

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

pagequeryinteger (int32)
Default: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
Default: 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.

Request example

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"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200A page of cities.

Responses · Field
FieldTypeDescription
itemsarray<PublicCityDto>nullable

Items of the requested page.

id
items[].id
string (uuid)

City id.

nameAr
items[].nameAr
stringnullable

Arabic name.

nameEn
items[].nameEn
stringnullable

English name.

code
items[].code
stringnullable

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 · Example response
{
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1
}
StatusDescription
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.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/geography/countries

#

List countries

API key + secret, or bearer tokenRequired scope: geography:read

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

Parameters

NameInTypeDescription
pagequeryinteger (int32)
Default: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
Default: 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.

Request example

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"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200A page of countries.

Responses · Field
FieldTypeDescription
itemsarray<PublicCountryDto>nullable

Items of the requested page.

id
items[].id
string (uuid)

Country id.

nameAr
items[].nameAr
stringnullable

Arabic name.

nameEn
items[].nameEn
stringnullable

English name.

code
items[].code
stringnullable

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 · Example response
{
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1
}
StatusDescription
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.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/geography/coverage

#

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

API key + secret, or bearer tokenRequired scope: 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.

Parameters

NameInTypeDescription
countryquerystring

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

cityquerystring

Required city: id, code or name.

Request example

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'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200Coverage of the city.

Responses · Field
FieldTypeDescription
cityPublicGeoNodeDto

A resolved geography node (id and both names).

id
city.id
string (uuid)

Resolved id.

nameAr
city.nameAr
stringnullable

Arabic name.

nameEn
city.nameEn
stringnullable

English name.

deliveryboolean

True when the company delivers to the city.

pickupboolean

True when the company picks up from the city.

200 · Example response
{
  "city": {
    "id": "a1d3c2b4-0e7f-4f5a-8a62-9c1e2d3b4a05",
    "nameAr": "جدة",
    "nameEn": "Jeddah"
  },
  "delivery": true,
  "pickup": false
}
StatusDescription
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.

Error responses share one body, described in the error reference. Error reference

GET

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

#

List the cities the company covers

API key + secret, or bearer tokenRequired scope: geography:read

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

Parameters

NameInTypeDescription
countryquerystring

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

pagequeryinteger (int32)
Default: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
Default: 25

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

searchquerystring

Optional text matched against names and city code.

Request example

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'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200A page of covered cities.

Responses · Field
FieldTypeDescription
itemsarray<PublicCoveredCityDto>nullable

Items of the requested page.

id
items[].id
string (uuid)

City id.

nameAr
items[].nameAr
stringnullable

Arabic name.

nameEn
items[].nameEn
stringnullable

English name.

code
items[].code
stringnullable

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 · Example response
{
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1
}
StatusDescription
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.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/geography/districts

#

List the districts of a city

API key + secret, or bearer tokenRequired scope: geography:read

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

Parameters

NameInTypeDescription
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)
Default: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
Default: 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.

Request example

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'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200A page of districts.

Responses · Field
FieldTypeDescription
itemsarray<PublicDistrictDto>nullable

Items of the requested page.

id
items[].id
string (uuid)

District id.

nameAr
items[].nameAr
stringnullable

Arabic name.

nameEn
items[].nameEn
stringnullable

English name.

code
items[].code
stringnullable

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 · Example response
{
  "page": 1,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1
}
StatusDescription
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.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/geography/resolve

#

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

API key + secret, or bearer tokenRequired scope: 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.

Parameters

NameInTypeDescription
countryquerystring

Country: id, ISO code or name.

cityquerystring

City: id, code or name.

districtquerystring

District: id, code or name.

Request example

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'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The resolved location.

Responses · Field
FieldTypeDescription
countryPublicGeoNodeDto

A resolved geography node (id and both names).

id
country.id
string (uuid)

Resolved id.

nameAr
country.nameAr
stringnullable

Arabic name.

nameEn
country.nameEn
stringnullable

English name.

cityPublicGeoNodeDto

A resolved geography node (id and both names).

id
city.id
string (uuid)

Resolved id.

nameAr
city.nameAr
stringnullable

Arabic name.

nameEn
city.nameEn
stringnullable

English name.

districtPublicGeoNodeDto

A resolved geography node (id and both names).

id
district.id
string (uuid)

Resolved id.

nameAr
district.nameAr
stringnullable

Arabic name.

nameEn
district.nameEn
stringnullable

English name.

200 · Example response
{
  "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"
  }
}
StatusDescription
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.

Error responses share one body, described in the error reference. Error reference