LAT15.5007° N LON32.5599° E ZOOM5.0 CRSEPSG:4326 COD-ABv03

Documentation

Using Sudan Atlas in your code

One package for Python and one for JavaScript, with the same data and identical results. They match Sudanese place names written any way, in Arabic or English, to official P-codes, and give you the names and boundaries of Sudan's 18 states, the Abyei PCA area and 189 localities.

Show examples in

Install

pip install sudan-atlas            # matcher, names and boundaries
pip install "sudan-atlas[geo]"     # adds GeoDataFrames (needs geopandas)
npm install sudan-atlas

Python 3.11 or later; Node 18 or later, or any modern browser. The place names, spellings and boundary files ship inside the package, so Python and Node work offline; in a browser the boundary files are fetched when first needed.

Your first match

Give match a name as it appears in your data. It returns the official place, its P-code, a score from 0 to 1 and how it was matched.

from sudan_atlas import match

match("Elfasher", level=2)
# {'pcode': 'SD02114', 'name_en': 'Al Fasher', 'name_ar': 'الفاشر', 'level': 2,
#  'score': 1.0, 'method': 'exact', 'alternatives': [...]}

match("الفاشر")["pcode"]      # 'SD02114'
import { match } from "sudan-atlas";

match("Elfasher", { level: 2 });
// { pcode: "SD02114", name_en: "Al Fasher", name_ar: "الفاشر", level: 2,
//   score: 1, method: "exact", alternatives: [...] }

match("الفاشر").pcode;        // "SD02114"

level is 1 for states and 2 for localities. Set it whenever you know it: "Kassala" is both a state and a locality, so match("Kassala") can't choose, while match("Kassala", level=1) returns SD11.

Your first map

Boundaries come as GeoJSON features in three detail levels: detailed, medium (the default) and light.

from sudan_atlas import geo        # needs the [geo] extra

localities = geo.localities("SD02")            # North Darfur's 17 localities
ax = localities.plot(edgecolor="white", color="#2c7fb8")
localities.apply(lambda r: ax.annotate(r.name_en, r.geometry.representative_point().coords[0],
                                       ha="center", fontsize=7), axis=1)
import { getLocalities, getFeature } from "sudan-atlas";
import { geoConicEqualArea, geoPath } from "d3-geo";

const features = await Promise.all(getLocalities("SD02").map((p) => getFeature(p.pcode, "light")));
const collection = { type: "FeatureCollection", features };
const path = geoPath(geoConicEqualArea().parallels([9, 21]).rotate([-30, 0]).fitSize([600, 600], collection));
const svg = features.map((f) => `<path d="${path(f)}" fill="#2c7fb8" stroke="white"/>`).join("");

Add P-codes to a spreadsheet

Match each distinct name once, then join the result back. Keep the method and score columns so you can review the uncertain rows.

import pandas as pd
from sudan_atlas import match

df = pd.read_csv("sites.csv")                     # columns: state, locality, people
results = {
    (loc, st): match(loc, state_hint=st, level=2)
    for loc, st in df[["locality", "state"]].drop_duplicates().itertuples(index=False)
}
df["pcode"] = [results[k]["pcode"] for k in zip(df.locality, df.state)]
df["match_method"] = [results[k]["method"] for k in zip(df.locality, df.state)]
df["match_score"] = [results[k]["score"] for k in zip(df.locality, df.state)]

df[df.pcode.isna()]       # rows to look at: no match, or a name that could be two places
import { match } from "sudan-atlas";

const cache = new Map();
for (const row of rows) {                       // rows: [{ state, locality, people }, ...]
  const key = `${row.locality}|${row.state}`;
  if (!cache.has(key)) cache.set(key, match(row.locality, { stateHint: row.state, level: 2 }));
  const r = cache.get(key);
  Object.assign(row, { pcode: r.pcode, match_method: r.method, match_score: r.score });
}
const toReview = rows.filter((row) => row.pcode === null);

Use a state hint

If your data has a state column, pass it. The matcher then looks only inside that state, which settles most look-alike names. The hint can be a P-code (SD15) or a state name in any spelling (Al Gezira, الجزيرة).

match("El Hasaheesa", state_hint="Al Gezira", level=2)["pcode"]   # 'SD15034' (Al Hasahisa)
match("Nyala Shimal", state_hint="SD03", level=2)["pcode"]        # 'SD03164'
match("El Hasaheesa", { stateHint: "Al Gezira", level: 2 }).pcode;   // "SD15034" (Al Hasahisa)
match("Nyala Shimal", { stateHint: "SD03", level: 2 }).pcode;        // "SD03164"

Handle uncertain names

The matcher never guesses silently. When the best place scores below the threshold, or a second place scores almost as high, pcode is empty and alternatives lists the best three candidates for a person to choose from.

r = match("Gallabat")
r["pcode"], r["method"]                       # (None, 'ambiguous')
[(a["pcode"], a["name_en"]) for a in r["alternatives"]]
# [('SD12077', 'Basundah'), ('SD12083', 'Galabat Ash-Shargiah'), ('SD12078', 'Al Galabat Al Gharbyah - Kassab')]
const r = match("Gallabat");
[r.pcode, r.method];                          // [null, "ambiguous"]
r.alternatives.map((a) => [a.pcode, a.name_en]);
// [["SD12077", "Basundah"], ["SD12083", "Galabat Ash-Shargiah"], ["SD12078", "Al Galabat Al Gharbyah - Kassab"]]

Gallabat town lies on the boundary between two localities, so both are offered. Decide with your own knowledge of the data, and store your decision so the next run doesn't ask again.

Maps with GeoPandas

With the [geo] extra, geo.states() and geo.localities() return GeoDataFrames in EPSG:4326 with the columns pcode, name_en, name_ar, level, parent_pcode and geometry. Join your data on pcode, never on names.

from sudan_atlas import geo

states = geo.states(resolution="light")
states.merge(my_totals, on="pcode", how="left").plot(column="people", legend=True, missing_kwds={"color": "#d4d4d8"})
// GeoPandas is Python only. In JavaScript, use getFeature() with any mapping library
// (D3, Leaflet, MapLibre): every feature is plain GeoJSON with the same properties.

Use it in a web page

No build step needed: import the package from jsDelivr. Boundary files are fetched from the same place when you first ask for them.

<script type="module">
  import { match, getFeature } from "https://cdn.jsdelivr.net/npm/sudan-atlas@0.1/dist/index.js";
  console.log(match("Omdurmaan", { level: 2 }).pcode);   // "SD01006"
</script>
# In the browser, use the JavaScript package (switch the examples above to JavaScript).

Serve the boundary files yourself

In Node and Python the files are read from the package itself. In a browser they come from jsDelivr unless you copy the package's data/ folder to your own server and point the package at it.

import { setDataUrl, getFeature } from "sudan-atlas";

setDataUrl("/static/sudan-atlas/");                 // your copy of node_modules/sudan-atlas/data/
const khartoum = await getFeature("SD01", "medium");
# Not needed in Python: get_feature() reads the files bundled with the package.

Without code: the map-maker

The map-maker does all of this in your browser: open a CSV or Excel file, check the uncertain matches, then download a map and your file with P-codes added. Your file never leaves your device. It reads HXL hashtags (such as #adm2+name, #adm2+code and #affected) to pick the columns, uses P-code columns as they are, and keeps the hashtags in the file you download. A file with latitude and longitude columns can be placed by coordinates instead: each point is counted in the locality that contains it, using the detailed boundaries, and drawn on the map; points outside Sudan or without coordinates are listed, not dropped.

Connect an AI assistant (MCP)

Sudan Atlas runs as a Model Context Protocol server, so assistants such as Claude can match place names and look up places for you. The address is https://atlas-sudan.vercel.app/api/mcp (Streamable HTTP). It is free, needs no key, only reads, and stores nothing you send.

# Claude Code
claude mcp add --transport http sudan-atlas https://atlas-sudan.vercel.app/api/mcp

# Other clients (mcp.json / claude_desktop_config.json, clients that support remote servers)
{ "mcpServers": { "sudan-atlas": { "type": "http", "url": "https://atlas-sudan.vercel.app/api/mcp" } } }
// Claude Code
claude mcp add --transport http sudan-atlas https://atlas-sudan.vercel.app/api/mcp

// Other clients (mcp.json / claude_desktop_config.json, clients that support remote servers)
{ "mcpServers": { "sudan-atlas": { "type": "http", "url": "https://atlas-sudan.vercel.app/api/mcp" } } }
ToolWhat it does
match_place_nameOne name to its P-code, with score, method and alternatives (optional state hint and level).
match_place_namesUp to 1,000 names at once, in order.
search_placesFind states and localities by part of a name.
get_placeNames, parent state, localities, area and estimated population for a P-code.
list_placesAll states, or the localities of the country or of one state.
get_boundaryA boundary as GeoJSON (light or medium detail).

Like the packages, the server never guesses silently: when a name could be two places it returns the candidates, and the assistant is told to ask you.

Privacy. Unlike the map-maker, which works entirely in your browser, the MCP server runs on our server: the names your assistant sends are processed there to answer the request, and are not stored or logged. Your assistant's own provider sees them too, under its own terms. Each address may make 60 requests a minute.

Reference: match()

match(name: str, state_hint: str | None = None, level: int | None = None) -> dict
match(name: string, options?: { stateHint?: string | null; level?: 1 | 2 | null }): MatchResult
FieldMeaning
pcodeThe P-code of the match, or empty (None / null) when there is no confident answer.
name_en, name_ar, levelThe official English and Arabic names and the level (1 state, 2 locality) of the match.
scoreSimilarity of the best candidate, from 0 to 1, rounded to four decimals.
methodexact (an official name), variant (a known spelling), fuzzy (a close spelling), ambiguous (two places too close to call) or none (nothing close enough).
alternativesThe next best candidates (up to three), each with pcode, name_en, name_ar, level and score.

Reference: Matcher

match() uses a shared matcher with the default settings. Create your own to change them.

from sudan_atlas import Matcher

strict = Matcher(threshold=0.9, margin=0.08)
strict.match("Kornoi", state_hint="North Darfur", level=2)
import { Matcher } from "sudan-atlas";

const strict = new Matcher(undefined, { threshold: 0.9, margin: 0.08 });
strict.match("Kornoi", { stateHint: "North Darfur", level: 2 });

threshold (default 0.82) is the lowest score accepted as a match. margin (default 0.05) is how far ahead of the second place the best candidate must be; closer than that, the result is ambiguous.

Reference: states and localities

PythonJavaScriptReturns
get_states()getStates()The 19 admin-1 units (18 states and the Abyei PCA area), sorted by P-code.
get_localities(state_pcode=None)getLocalities(statePcode?)All 189 localities, or those of one state.
–getPlace(pcode)One place by P-code, or undefined.

Each place has pcode, name_en, name_ar, level, parent_pcode (SD for states) and point, a [longitude, latitude] inside the place that is good for a label.

get_states()[0]
# {'pcode': 'SD01', 'name_en': 'Khartoum', 'name_ar': 'الخرطوم', 'level': 1,
#  'parent_pcode': 'SD', 'point': [33.1352, 15.915]}
getStates()[0];
// { pcode: "SD01", name_en: "Khartoum", name_ar: "الخرطوم", level: 1,
//   parent_pcode: "SD", point: [33.1352, 15.915] }

Reference: boundaries

PythonJavaScriptReturns
get_feature(pcode, resolution="medium")await getFeature(pcode, resolution = "medium")A GeoJSON Feature with the place's properties.
geo.states(resolution="medium")–GeoDataFrame of the 18 states and the Abyei PCA area (needs [geo]).
geo.localities(state_pcode=None, resolution="medium")–GeoDataFrame of localities (needs [geo]).
–setDataUrl(url)Load boundary files from your own address (browser).

resolution is detailed (the COD-AB geometry), medium or light (simplified for web maps, with shared borders kept intact).

Reference: P-codes

P-codes are the official codes from OCHA's Common Operational Datasets. SD is Sudan; a state adds two digits (SD15, Aj Jazirah); a locality adds three more (SD15034, Al Hasahisa). Join datasets on P-codes, never on names: names have many spellings, P-codes have one.

Reference: data files

The same files are in both packages and in the repository's data/ folder, and on jsDelivr under https://cdn.jsdelivr.net/npm/sudan-atlas@0.1/data/.

PathContents
boundaries/{detailed|medium|light}/adm{1|2}.geojsonStates (adm1) and localities (adm2) as GeoJSON, EPSG:4326.
boundaries/{detailed|medium|light}/adm{1|2}.topojsonThe same as TopoJSON, smaller for the web.
places.jsonThe 208 places with names, levels, parents and label points.
variants.json, variants_osm.jsonKnown spellings of each place, with their sources (the OpenStreetMap ones under the ODbL).
normalisation.jsonThe rules that turn a name into a matching key, shared by both packages.

Reference: versions and constants

PythonJavaScriptValue
sudan_atlas.__version__VERSIONThe package version (0.1.3).
DATA_VERSIONDATA_VERSIONThe data release (2026.1).
RESOLUTIONSRESOLUTIONSdetailed, medium, light.
–DEFAULT_THRESHOLD, DEFAULT_MARGIN0.82 and 0.05.

How matching works

  1. Normalise. Both the input and every known name become a matching key: Arabic letter forms are unified (أ إ آ → ا, ة → ه, ى → ي), diacritics and articles (Al-, El-, ال) are set aside, common transliteration differences are merged (ou/u, ei/ai), and words such as "locality" or "محلية" are dropped.
  2. Exact. The key is compared with the official English and Arabic names of every place.
  3. Known spellings. Then with more than a thousand reviewed spellings gathered from GeoNames, Wikidata, OpenStreetMap and humanitarian datasets.
  4. Fuzzy. Then with every name by similarity, which catches typos and new spellings.
  5. Decide. The best candidate is accepted only if it scores at least 0.82 and is at least 0.05 ahead of the next place. Otherwise you get the candidates and the decision is yours.

The Python and JavaScript matchers share the same rules file and are tested against the same expected results, so they return identical answers.

How accurate it is

We tested the matcher on 299 place names copied as written from eight public datasets on HDX: refugee sites (UNHCR), people reached and who does what where (OCHA), displacement (IOM DTM), food insecurity (IPC), schools, floods and population tables. 253 of them should match a state or locality. The other 46 should match nothing: camps and villages, names shared by several places, and stray header and total rows. With the state given as a hint, as most humanitarian spreadsheets allow:

  • 94.9% of the 253 matched to the right place first time
  • 99.6% (252 of 253) had the right place among the top three
  • 0 of 299 matched to a wrong place on this set: when it wasn't sure, it asked (13 names)

What these figures don't show. The threshold (0.82) was chosen on this same set of names, so the results describe this set and are not an independent test: on new data the matcher will make mistakes, wrong matches included. Without a state hint it is right first time for 85.0% and names a wrong place for 2.3% of the names (7 of 299), so give the state whenever you have it. None of the test names was added to the matcher's spellings by hand; 47 are spellings it already knew from GeoNames, Wikidata, COD-AB or OpenStreetMap. If you find a wrong match, please report it on GitHub.

The full evaluation, with every failure, is in MATCHER_EVALUATION.md, and the names themselves are in match_cases.csv.

Sources and licences

Boundaries and P-codes: OCHA's Common Operational Dataset for Sudan (COD-AB, version v03), CC BY 3.0 IGO. Spellings: GeoNames (CC BY 4.0), Wikidata (CC0) and OpenStreetMap (ODbL, kept in a separate file). Code: MIT. Sudan Atlas's own data: CC BY 4.0. Boundaries do not imply any opinion on the legal status of any territory. More on the data and sources page. To cite Sudan Atlas: doi:10.5281/zenodo.24191932.