morocco-communes
Every commune in Morocco as open data, rebuilt from the census spreadsheets, with an API and an MCP server for AI assistants.
- Role
- Design and build
- Client
- Personal project
- Year
- 2026
- Stack
-
- Data
- TypeScript, HCP census workbooks, OpenStreetMap, TopoJSON
- Site and API
- Astro, Hono, Cloudflare Pages
- AI
- MCP TypeScript SDK
- Packages
- npm, PyPI
Why I built it
I was designing a way to turn Moroccan delivery addresses into a place on a map. When a street or a building can’t be found, what’s left to fall back on is the commune, Morocco’s smallest administrative unit. HCP, the country’s statistics office, publishes every commune with its official code and its census figures, but only as Excel workbooks.
Row 314 of the 2024 one is the commune of Tanger. In Excel its code reads
01.511.01.0. Click the cell and the formula bar says 1511010.
Read the sheet with a program, like pandas in Python, and Tanger’s code comes
back without the zero that puts it in région 01. Every région, province,
commune and arrondissement in the workbook is stored like that. So before
anything could be built on the census, the codes had to be put back together.
What it is
An open dataset of every commune in Morocco, on HCP’s official codes, with the 2014 and 2024 censuses, the 2024 count of businesses and jobs, the urban housing stock, and boundaries from OpenStreetMap. Every commune, province and région has a page in English and French. Programs can read the same data through a free API with no key, or install it from npm or PyPI and use it offline. And an MCP server lets an AI assistant look things up in it directly.
First, putting the zeros back
A code is the hierarchy written out. Ketama, a rural commune in the province
of Al Hoceima, is 01.051.09.15:
Padding the number back to 9 digits gets most of the way. It breaks on width.
Tanger’s code ends in a single digit, and the arrondissements under it end in
2: Mghogha is 01.511.01.05. HCP gives the cities split into arrondissements a
shorter last group than everything around them. So the build composes each
code from the row’s own number and its province’s, and keeps the last group at
the width HCP published.
The workbook has no parent column either. It goes over the country 4 times on one sheet: the totals by province, then the urban population, then the rural, then the full detail down to each commune. In that last pass the hierarchy is the order of the rows. A province is followed by its urban communes, then by its cercles, and each cercle by its rural communes:
The build starts at the last pass, walks down, and keeps track of the région, province and cercle it’s in.
It reads the workbooks with a reader of its own, which hands over every cell as it’s written. A code HCP saved as text keeps its zeros that way, and the spaces the 2014 workbook marks as meaningful stay where they are. Without them, “Arrondissements” ran straight into the name after it.
HCP can replace a workbook without notice, so each one is pinned by its checksum. When a file changes upstream, the build stops and prints the old and new checksums, and the pin only moves once somebody has read the new file. Each stage then checks its own figures before it writes them: the indicators, the 2014 figures, the businesses, the housing, the borders. The build stops at the first one that doesn’t hold together.
Then the codes changed
The 2015 territorial reform renumbered the cercles, and a commune’s code
carries its cercle. So a commune could change code between the 2 censuses
without changing at all. Ait Kamra, in Al Hoceima, is 01.051.05.01 in 2014
and 01.051.11.01 in 2024.
A commune that kept its code joins directly. The cities split into arrondissements have no commune row in the 2014 workbook, so their 2014 figure is the sum of their arrondissements. The communes whose code changed go through a crosswalk, matched by name inside their province, and each match keeps its evidence:
{
"code2014": "01.051.05.01",
"code2024": "01.051.11.01",
"name2024": "Ait Kamra",
"method": "exact_name_in_province",
"evidence": {
"province": "01051",
"normalisedNameMatch": true,
"candidatesInProvince": 3,
"population2014": 7685,
"population2024": 8269,
"populationRatio": 1.076
}
}
Then the boundaries
The boundaries come from OpenStreetMap. Its mappers tag each commune’s boundary with the commune’s HCP code, so the build joins the two on that code, and a boundary whose code matches nothing goes on a list of its own. Every commune but one has a boundary.
The rest of the map is worked out from them. 2 communes border each other when their boundaries share a stretch, 2 points in a row that both use, so 2 that meet at a corner aren’t neighbours. A commune’s centre is the point inside it furthest from any edge, because the average of its corners lands outside for about one commune in 30. And to find the commune a point is in, the boundaries are cut into square tiles, split in 4 wherever one gets crowded, so a lookup reads one small file.
Each boundary is stored on a grid 2 to 6 m wide, set by the size of its région.
At the end come the files: JSON and CSV for every level, a TopoJSON map per région, the API’s files, and a record of each source’s checksum, licence and year.
Then the names people type
Search takes French, Arabic, a slug or an old name, and the site’s Find a place
box, the API and the MCP server’s search tool all use it. It folds what Arabic
spelling varies on: the forms of alef, a final ه written for ة, the vowel marks
and the tatweel. A name spelt another way is matched by its consonants, and the
old and foreign names no folding reaches are on a list made by hand. Each of
these finds its place on the live API:
titwan Tétouan by its consonants
jdida El Jadida by its consonants
Ktama Ketama by its consonants
Fez Fès from the list
Port Lyautey Kénitra from the list
طَنجة Tanger vowel mark folded
طنـجة Tanger tatweel folded
الجديده El Jadida ه read as ة
Casa Casablanca as a prefix
Search runs on an index the build writes. It stores each name’s folded forms and trigram count ahead of time, because working them out for every candidate is what made a search for a common name cost 27 ms against a 10 ms budget. Now one costs well under a millisecond. Each entry is a list of fields rather than an object, which makes the index about a third the size to send.
Serving it for nothing
Most of the API is a lookup of one thing, so most of it is files. The build writes every commune, province and région as JSON and GeoJSON, and Cloudflare serves them as static files. Code only runs where it has to: search, finding the commune a point is in, filtered lists, and the MCP server.
The site is on Cloudflare Pages, where a _routes.json file decides which
requests reach the code. This one sends /api/* and /mcp to it, and takes
every JSON and GeoJSON file under /api back out:
{
"version": 1,
"include": ["/api/*", "/mcp"],
"exclude": ["/api/*.json", "/api/*.geojson"]
}
A static file never starts the code, so it doesn’t count against the free plan’s requests.
Cloudflare’s docs show wildcards at the end of a path. I tested one in the middle, before a file extension, on a throwaway project first. It works, so I’ve opened a PR to add it to their docs.
Each file is sent with an hour’s cache, and a day in which a stale copy may be served while it’s refreshed. A dataset version never changes, since a correction ships as a new deploy, so a copy a browser already holds never reaches Cloudflare at all.
A list filtered once, in code order, is one of those files too. A list sorted by a figure, or filtered twice, is worked out from one table of every commune’s figures that the function keeps in memory, so ranking the communes never means reading their files. The commune picker for forms reads only the files: a région, province and commune dropdown in plain HTML or React that posts the commune’s HCP code with the form, so it costs nothing however busy the form gets.
Then I handed it to a model
MCP is a standard way for an AI assistant to use tools. The server’s tools
are read-only: search finds a place by name, in French or Arabic or
misspelled. get_commune and get_unit return a place and what’s above and
below it. commune_at finds the commune a point is in, and communes_near
lists the ones around it. list_communes filters and sorts by any census
figure, and get_indicators, get_economy and get_housing return the
figures themselves.
How do I know it answers correctly?
An eval is a fixed set of questions whose answers are known before they’re asked. Each one goes to Claude, run from a script, with the MCP server as its only tools. It starts in an empty folder with no settings and a one-line instruction to answer and use the tools where they help, so all it knows about the data is what the tools’ descriptions tell it.
The questions cover lookups, misspelled and Arabic names, coordinates, rankings, what changed between the censuses, which commune borders which, and figures that don’t exist, where the right answer says so.
The expected answers are worked out from the published data each time the eval runs, so a rebuild can’t leave it checking old numbers. The unemployment question expects whichever commune over 50,000 people has the highest rate, and that rate:
const jobless = [...over50k].sort(
(a, b) => (labour(b.code).unemploymentRate ?? -1) - (labour(a.code).unemploymentRate ?? -1),
)[0]!;
{
id: "jobless-50k",
category: "indicators",
question: "Among communes of more than 50,000 people, where is unemployment highest?",
expect: {
names: [[jobless.name.fr]],
numbers: [labour(jobless.code).unemploymentRate!],
tools: ["list_communes"],
maxCalls: 3,
},
},
An answer passes when it names the right place, in any spelling on the list,
and states the right figures. Figures are read however the model writes them:
6,124, 6 124, Arabic-Indic digits or a decimal comma. It has to have called
the tools the question needs, too. Each question also has a budget of calls,
and an answer over it still passes but is marked slow.
Every run records what each question spent: the tokens the model read and wrote, which are what it’s billed by, how many it read back from a cache, the cost at list price, and how long it took to start answering. It also records what it ran on: the model, the version of the client, the commit, the dataset version and the exact tool list the server sent. So 2 runs compare question by question, and a change to one tool’s description shows up as a number.
81 calls for one question
“Among communes of more than 50,000 people, where is unemployment highest?” takes one call: list the communes over 50,000, sorted by unemployment rate. In one run, Haiku sent this:
{ "min_population": 50000, "sort": "\"-labour.unemploymentRate\"" }
The quotes are inside the string. The server refused it as a figure it didn’t know. Haiku tried a second name, was refused again, and gave up on sorting. It read the communes one at a time instead: 81 tool calls, and the right answer at the end.
A value wrapped in one pair of quotes can only mean the value inside them, so the server reads it that way now, and the same question takes 1 call.
“Which commune in Morocco has the most permanent jobs in its businesses?” took Sonnet 56 calls. The cities split into arrondissements carry no business figures of their own, and no tool returned their arrondissements together, so it read them one by one. They come in one file now, the figure tools take the arrondissement as a level, and the question takes 1 call.
Doing the work before anyone asks
The eval found 8 of these. Each was a right answer that cost too much, or a tool a model couldn’t use from its description, and every fix moved work out of the answer, into the build or into a single call.
The sums were the biggest. HCP counts the businesses of 6 cities only by
arrondissement, so every question about one of them ended with the model
reading 16 or 41 rows into its context, about 6,000 tokens of JSON, and adding
them up with nobody checking. A count’s total is the exact sum of its parts, so
the build now publishes each city’s, marked basis: arrondissement_sum.
Casablanca’s is checked against a second grouping of the same 16
arrondissements, the 8 préfectures d’arrondissements HCP publishes. Asked how
many businesses Casablanca has, a model makes 2 calls now and says where the
figure came from.
3 more put an answer in one call. get_commune returns a city’s arrondissements
with their population, get_indicators takes a level and returns every unit of
it at once, and get_unit returns a province with the units under it named, so
a model no longer counts cercles off a page of communes. The other 2 were words:
a name 2 levels share, like Taroudannt, is read at the level a filter asks for,
and the sort parameter says unemployment is under labour, where Haiku had
looked in employmentStatus.
The ratios are worked out per request instead of published. Sorted by jobs per 1,000 people, a list puts a count against the people it serves, where the raw count only ranks the biggest places first, and each row says the division it came from.
What a question costs
The latest run asked the whole set through the live server on 2 of Anthropic’s models, Sonnet 5 and Haiku 4.5, and both answered all 49 correctly. At API list price, a question cost a median of $0.017 on Sonnet and $0.009 on Haiku, and the whole set $1.19 and $0.61. Here’s what the models read and wrote on the way:
On every turn a model reads the same instructions and tool list again, and those come back from a cache at a tenth of the price. A question took a median of 13 seconds on Sonnet and 11 on Haiku.