Search Locations
curl --request GET \
--url https://api.majarrah.io/v1/locations \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.majarrah.io/v1/locations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.majarrah.io/v1/locations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.majarrah.io/v1/locations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.majarrah.io/v1/locations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.majarrah.io/v1/locations")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.majarrah.io/v1/locations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"object": "list",
"data": [
{
"object": "city",
"id": 57834912,
"name_ar": "الرياض",
"name_en": "Riyadh",
"district_count": 312
}
],
"total": 1
}
{
"object": "list",
"data": [
{
"object": "district",
"id": 23741856,
"name_ar": "الملقا",
"name_en": "Al Malqa",
"city_id": 57834912,
"city_name_ar": "الرياض",
"city_name_en": "Riyadh"
}
],
"total": 1
}
{
"object": "city",
"id": 57834912,
"name_ar": "الرياض",
"name_en": "Riyadh",
"districts": [
{ "id": 23741856, "name_ar": "الملقا", "name_en": "Al Malqa" },
{ "id": 34892710, "name_ar": "النخيل", "name_en": "Al Nakheel" }
]
}
{
"object": "list",
"data": [],
"total": 0,
"message": "No city matched 'xyz'. Verify the city name using ?city=xyz."
}
{
"error": "missing_params",
"message": "Provide at least one of: city, district."
}
{
"error": "invalid_param",
"message": "city must be at least 2 characters.",
"field": "city"
}
{
"error": "unauthorized",
"message": "Valid Bearer API key required."
}
Locations
Search Locations
Look up cities and districts by name. Returns numeric IDs to use in POST /decisions.
GET
/
locations
Search Locations
curl --request GET \
--url https://api.majarrah.io/v1/locations \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.majarrah.io/v1/locations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.majarrah.io/v1/locations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.majarrah.io/v1/locations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.majarrah.io/v1/locations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.majarrah.io/v1/locations")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.majarrah.io/v1/locations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"object": "list",
"data": [
{
"object": "city",
"id": 57834912,
"name_ar": "الرياض",
"name_en": "Riyadh",
"district_count": 312
}
],
"total": 1
}
{
"object": "list",
"data": [
{
"object": "district",
"id": 23741856,
"name_ar": "الملقا",
"name_en": "Al Malqa",
"city_id": 57834912,
"city_name_ar": "الرياض",
"city_name_en": "Riyadh"
}
],
"total": 1
}
{
"object": "city",
"id": 57834912,
"name_ar": "الرياض",
"name_en": "Riyadh",
"districts": [
{ "id": 23741856, "name_ar": "الملقا", "name_en": "Al Malqa" },
{ "id": 34892710, "name_ar": "النخيل", "name_en": "Al Nakheel" }
]
}
{
"object": "list",
"data": [],
"total": 0,
"message": "No city matched 'xyz'. Verify the city name using ?city=xyz."
}
{
"error": "missing_params",
"message": "Provide at least one of: city, district."
}
{
"error": "invalid_param",
"message": "city must be at least 2 characters.",
"field": "city"
}
{
"error": "unauthorized",
"message": "Valid Bearer API key required."
}
Query parameters
At least one ofcity or district is required.
string
City name to search. Accepts Arabic or English, and handles partial/transliterated input (e.g.
"ryad" matches "Riyadh"). Minimum 2 characters.When used alone, returns matching city results. When used alongside district, scopes the district search to that city.string
District or neighbourhood name to search. Accepts Arabic or English. Minimum 2 characters.When used alone, searches districts across all cities. When used with
city, scopes results to that city.boolean
Pass
true alongside city to return all districts of that city as a city object. No search is performed — every district is returned.Response
Search response (object: "list")
Returned for city and district searches.
string
Always
"list" for search responses.array
Matching cities and/or districts, max 20 per request.
Show item fields
Show item fields
string
"city" or "district".number
Unique numeric ID. Pass as
city_id or district_id in POST /decisions.string
Official Arabic name.
string
English transliteration.
number
Number of districts. Only on
object: "city" items.number
Parent city ID. Only on
object: "district" items.string
Arabic name of the parent city. Only on
object: "district" items.string
English name of the parent city. Only on
object: "district" items.number
Number of items returned.
string
Only present when
city was supplied but no city matched. Contains a hint to verify the city name.City object response (object: "city")
Returned when districts=true is passed alongside city.
string
Always
"city".number
City numeric ID.
string
Official Arabic name.
string
English transliteration.
array
All districts in this city. Each item has
id, name_ar, name_en.Examples
curl "https://api.majarrah.io/v1/locations?city=ryad" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.majarrah.io/v1/locations?city=جدة" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.majarrah.io/v1/locations?district=malqa&city=Riyadh" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.majarrah.io/v1/locations?district=corniche" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.majarrah.io/v1/locations?city=Riyadh&districts=true" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"object": "list",
"data": [
{
"object": "city",
"id": 57834912,
"name_ar": "الرياض",
"name_en": "Riyadh",
"district_count": 312
}
],
"total": 1
}
{
"object": "list",
"data": [
{
"object": "district",
"id": 23741856,
"name_ar": "الملقا",
"name_en": "Al Malqa",
"city_id": 57834912,
"city_name_ar": "الرياض",
"city_name_en": "Riyadh"
}
],
"total": 1
}
{
"object": "city",
"id": 57834912,
"name_ar": "الرياض",
"name_en": "Riyadh",
"districts": [
{ "id": 23741856, "name_ar": "الملقا", "name_en": "Al Malqa" },
{ "id": 34892710, "name_ar": "النخيل", "name_en": "Al Nakheel" }
]
}
{
"object": "list",
"data": [],
"total": 0,
"message": "No city matched 'xyz'. Verify the city name using ?city=xyz."
}
{
"error": "missing_params",
"message": "Provide at least one of: city, district."
}
{
"error": "invalid_param",
"message": "city must be at least 2 characters.",
"field": "city"
}
{
"error": "unauthorized",
"message": "Valid Bearer API key required."
}
Was this page helpful?