> ## Documentation Index
> Fetch the complete documentation index at: https://docs.majarrah.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Locations

> Look up cities and districts by name. Returns numeric IDs to use in POST /decisions.

## Query parameters

At least one of `city` or `district` is required.

<ParamField query="city" type="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.
</ParamField>

<ParamField query="district" type="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.
</ParamField>

<ParamField query="districts" type="boolean">
  Pass `true` alongside `city` to return all districts of that city as a city object. No search is performed — every district is returned.
</ParamField>

***

## Response

### Search response (`object: "list"`)

Returned for city and district searches.

<ResponseField name="object" type="string">
  Always `"list"` for search responses.
</ResponseField>

<ResponseField name="data" type="array">
  Matching cities and/or districts, max 20 per request.

  <Expandable title="item fields">
    <ResponseField name="object" type="string">
      `"city"` or `"district"`.
    </ResponseField>

    <ResponseField name="id" type="number">
      Unique numeric ID. Pass as `city_id` or `district_id` in `POST /decisions`.
    </ResponseField>

    <ResponseField name="name_ar" type="string">
      Official Arabic name.
    </ResponseField>

    <ResponseField name="name_en" type="string">
      English transliteration.
    </ResponseField>

    <ResponseField name="district_count" type="number">
      Number of districts. Only on `object: "city"` items.
    </ResponseField>

    <ResponseField name="city_id" type="number">
      Parent city ID. Only on `object: "district"` items.
    </ResponseField>

    <ResponseField name="city_name_ar" type="string">
      Arabic name of the parent city. Only on `object: "district"` items.
    </ResponseField>

    <ResponseField name="city_name_en" type="string">
      English name of the parent city. Only on `object: "district"` items.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number">
  Number of items returned.
</ResponseField>

<ResponseField name="message" type="string">
  Only present when `city` was supplied but no city matched. Contains a hint to verify the city name.
</ResponseField>

### City object response (`object: "city"`)

Returned when `districts=true` is passed alongside `city`.

<ResponseField name="object" type="string">
  Always `"city"`.
</ResponseField>

<ResponseField name="id" type="number">
  City numeric ID.
</ResponseField>

<ResponseField name="name_ar" type="string">
  Official Arabic name.
</ResponseField>

<ResponseField name="name_en" type="string">
  English transliteration.
</ResponseField>

<ResponseField name="districts" type="array">
  All districts in this city. Each item has `id`, `name_ar`, `name_en`.
</ResponseField>

***

## Examples

<CodeGroup>
  ```bash Search by city name (English) theme={null}
  curl "https://api.majarrah.io/v1/locations?city=ryad" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Search by city name (Arabic) theme={null}
  curl "https://api.majarrah.io/v1/locations?city=جدة" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Search districts within a city theme={null}
  curl "https://api.majarrah.io/v1/locations?district=malqa&city=Riyadh" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Search districts across all cities theme={null}
  curl "https://api.majarrah.io/v1/locations?district=corniche" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash All districts of a city theme={null}
  curl "https://api.majarrah.io/v1/locations?city=Riyadh&districts=true" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 - City search theme={null}
  {
    "object": "list",
    "data": [
      {
        "object": "city",
        "id": 57834912,
        "name_ar": "الرياض",
        "name_en": "Riyadh",
        "district_count": 312
      }
    ],
    "total": 1
  }
  ```

  ```json 200 - District search (scoped to city) theme={null}
  {
    "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
  }
  ```

  ```json 200 - All districts of a city theme={null}
  {
    "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" }
    ]
  }
  ```

  ```json 200 - City not found theme={null}
  {
    "object": "list",
    "data": [],
    "total": 0,
    "message": "No city matched 'xyz'. Verify the city name using ?city=xyz."
  }
  ```

  ```json 400 - Missing params theme={null}
  {
    "error": "missing_params",
    "message": "Provide at least one of: city, district."
  }
  ```

  ```json 400 - Value too short theme={null}
  {
    "error": "invalid_param",
    "message": "city must be at least 2 characters.",
    "field": "city"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "error": "unauthorized",
    "message": "Valid Bearer API key required."
  }
  ```
</ResponseExample>