README

Open, bilingual dataset of Saudi Arabia's administrative hierarchy — 13 regions, 15,513 cities, and 21,235 districts — from the MOMRAH Unified Municipal Coding. Every record has Arabic and English names and stable integer IDs linked by foreign keys.

This is a lookup (coding) dataset: no coordinates, no boundaries, no composite IDs.

What's in this repo

data/source/ — the canonical JSON (regions.json, cities.json, districts.json).
data/dist/ — generated outputs (JSON, CSV, MySQL, PostgreSQL); regenerated by the build.
packages/js/ — the saudi-municipal-coding npm package.
packages/php/ — the yasseralsamman/saudi-municipal-coding Composer package.
schemas/ — JSON Schema for each entity.
scripts/ — the build, validate, and stats pipeline.

Data formats

Format	Files
JSON	`data/dist/{regions,cities,districts}.json`
CSV	`data/dist/{regions,cities,districts}.csv`
MySQL	`data/dist/mysql.sql`
PostgreSQL	`data/dist/postgres.sql`
SQLite	`saudi-municipal-coding.sqlite` (attached to each GitHub Release)

Install

JavaScript / TypeScript

npm install saudi-municipal-coding

import { regions, cities, districts, findDistrict, districtsInCity } from 'saudi-municipal-coding';

regions.length;   // 13
cities.length;    // 15513
districts.length; // 21235

findDistrict(2510);     // { district_id, city_id, region_id, name_ar, name_en }
districtsInCity(17743); // districts of a city

PHP

composer require yasseralsamman/saudi-municipal-coding

use SaudiMunicipalCoding\Dataset;

Dataset::findRegion(1)?->name_en;   // 'Riyadh'
Dataset::districtsInCity(17743);    // districts of a city (keyed by district_id)

The data model

region_id, city_id, and district_id are independent integers. Cities reference a region; districts reference both a city and a region, and a district's region_id always equals its city's region. District names are not unique by themselves — district_id is the unique key. See DATA_REFERENCE.md for the full dictionary.

What's not included

Geographic coordinates or boundary polygons.
Population, region codes, or capital cities.
Composite/encoded identifiers — the IDs here are plain integers.

Development

pnpm install
pnpm run validate   # integrity checks on data/source
pnpm run build      # regenerate data/dist + package data
pnpm run stats      # counts + file sizes
pnpm test           # JS + PHP package tests
pnpm run lint       # Biome

data/dist/ and packages/*/data/ are committed; CI rebuilds and fails if they drift from a fresh build (pnpm run check:dist-clean). See CONTRIBUTING.md.

License

Code (scripts, both packages): MIT.
Data (data/source/ and data/dist/): CC0-1.0 — a public-domain dedication, so no attribution is required.

yasseralsamman / saudi-municipal-coding

Maintainers

Package info

Statistics

Security