Sudan Atlas

io.github.aminshennanPublished by GitHub account aminshennanv0.1.5Updated Nov 22, 2026

Match Sudanese place names (Arabic or English) to official P-codes; get places and boundaries.

The publisher's own server: Red Atlas Api

VerifiedStreamable HTTPWeb executableLocation & LifestyleData & Analytics

Overview

AI-generated overview

Matches Sudanese place names in Arabic or English to official P-codes and returns names, population estimates and GeoJSON boundaries.

What you can do
  • Match one place name, or up to 1,000 at once, to an official P-code with a confidence score and alternatives
  • Search states and localities by partial English or Arabic name
  • Look up official names, level, parent state, area and estimated population for a P-code
  • List all 19 admin-1 units or the localities of the country or one state
  • Fetch a place boundary as a GeoJSON Feature at light or medium detail
When to use it
Useful when working with Sudanese administrative data: cleaning a spreadsheet of place names before mapping or joining it to humanitarian datasets, or looking up official names, codes, populations and boundaries for states and localities.
Requirements
A remote MCP endpoint over streamable HTTP; no account, key or local runtime is needed. The README notes a limit of 60 requests per minute per address.
Before you install
Place names you send are processed on the server (the site says they are not stored or logged). Matches can be wrong or ambiguous: when confidence is low the P-code is null and candidates are returned, so a person should decide. Population figures are mid-2025 estimates, not counts, and boundaries do not imply any opinion on territorial status.

Installation

In SourceWeft

  1. Open Sudan Atlas in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.aminshennan%2Fsudan-atlas/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "sudan-atlas": {
      "type": "http",
      "url": "https://atlas-sudan.vercel.app/api/mcp"
    }
  }
}

README

[Sudan Atlas logo: Sudan drawn in dots, with Khartoum in green]

Sudan Atlas toolkit

[DOI] [npm] [PyPI] [mcptry]

An open toolkit that turns messy Sudanese place names into official codes, and gives the names (Arabic and English) and boundaries of Sudan's 18 states, the Abyei PCA area and 189 localities. It contains:

  • Python and JavaScript packages (sudan-atlas on PyPI and npm) with the same matcher, data and results;
  • the data: boundaries following OCHA's COD-AB for Sudan (v03), a gazetteer of reviewed spellings, and the pipeline that builds them;
  • a skill for AI assistants, and a Claude Code plugin that adds it together with the Sudan Atlas MCP server;
  • an evaluation of the matcher on real humanitarian data.

Status: packages 0.1.5 on npm and PyPI; data release 2026.1 (COD-AB Sudan v03).

Use it online: the website atlas-sudan.vercel.app is built on this toolkit: a map of every state and locality, a map-maker that turns a spreadsheet of place names into a map (in the browser; files never leave your device), and the documentation.

Quick start

JavaScript (npm install sudan-atlas)

js
import { match, getFeature } from "sudan-atlas";match("El Hasaheesa", { stateHint: "Al Gezira", level: 2 }).pcode; // "SD15034"const shape = await getFeature("SD15034", "medium");               // GeoJSON Feature

Python (pip install sudan-atlas, or "sudan-atlas[geo]" for GeoDataFrames)

python
from sudan_atlas import match, get_localitiesmatch("الفاشر", level=2)["pcode"]  # 'SD02114'get_localities("SD15")              # the localities of Aj Jazirah

In a browser with no build step: import { match } from "https://cdn.jsdelivr.net/npm/[email protected]/dist/index.js"; the data files are on jsDelivr too, under …/[email protected]/data/.

AI assistants: in Claude Code, add the plugin, which brings the skill and the MCP server:

text
/plugin marketplace add aminshennan/sudan-atlas/plugin install sudan-atlas@sudan-atlas

Or add the server alone, in any client that supports remote MCP servers: claude mcp add --transport http sudan-atlas https://atlas-sudan.vercel.app/api/mcp. The skill works in other agents too: copy plugins/sudan-atlas/skills/sudan-atlas/ into the agent's skills folder. Names sent to the MCP server are processed on the server and not stored; each address may make 60 requests a minute.

Examples: a D3 choropleth from a messy spreadsheet, a state-and-locality picker, and a Python notebook.

What a match returns

js
{  pcode: "SD15034", name_en: "Al Hasahisa", name_ar: "الحصاحيصا", level: 2,  score: 0.9,            // 0 to 1  method: "fuzzy",         // exact, variant or fuzzy; ambiguous or none when there is no match  alternatives: [ ... ]    // the next three candidates, each with pcode, names, level and score}

When the best candidate scores below 0.82, or another place scores almost as high, pcode is null (None in Python) and alternatives lists the candidates: the matcher never guesses silently. "Gallabat" lies on a locality border and "Abyei" can mean the Abyei PCA area or the West Kordofan locality, so both come back as ambiguous for a person to decide. A state hint (a P-code or a state name in any spelling) and a level (1 = state, 2 = locality) settle most ambiguity.

We tested the matcher on 299 place names copied from eight public HDX datasets (UNHCR refugee sites, OCHA people reached and 3W, IOM DTM, IPC, schools, floods and population tables): 253 that should match a state or locality and 46 that should match nothing (camps, villages, names shared by several places, header and total rows). With a state hint, it finds the right place first time for 94.9 % of the 253, puts it among the top three for 99.6 %, and named no wrong place for any of the 299. Without a state hint: 85.0 % first time and 2.3 % wrong matches. The threshold was chosen on this same set, so these figures describe it rather than an independent test, and new data will produce some wrong matches; please report them. Details and every failure: docs/MATCHER_EVALUATION.md. The Python and JavaScript packages share the same rules and return identical results.

Independent test. We then measured the matcher once, unchanged, on 148 names it had never seen, from 16 other HDX datasets (docs/MATCHER_HOLDOUT.md). With a state hint it found the right place first time for 90.2 % of the 92 state and locality names (95 % range 82–95 %) and sent one of them to a wrong place. But 9 of the 56 village, camp and market names, which should match nothing, were matched to a locality, mostly where the data had no state column or the site is named after its town. Give the state whenever you have it, and check any match that comes from a village, camp, market or site column.

What it does

  • Name matching: El Fasher, Al Fashir and الفاشر all resolve to the same official P-code, with a confidence score and alternatives.
  • Boundaries: states (admin 1) and localities (admin 2) as GeoJSON and TopoJSON at three resolutions, following OCHA's COD-AB exactly.
  • Bilingual: every feature carries pcode, name_en and name_ar.
  • Runs on your machine: the packages ship the data as files and match locally, with no network calls (boundaries can also be loaded from a CDN in the browser).

Repository layout

text
data/          boundaries, gazetteer and test cases (one source of truth)pipeline/      Python scripts that rebuild data/ from data/raw/packages/js/   npm package: data + matcher (TypeScript)packages/py/   PyPI package: same API (Python)plugins/       Claude Code plugin: the skill plus the MCP serverexamples/      D3 map, dropdown form, Python notebookdocs/          DATA_POLICY.md, SOURCES.md, GAZETTEER.md, MATCHER_EVALUATION.md

Citing Sudan Atlas

If you use Sudan Atlas in a report, paper or product, please cite it:

Shennan, A. (2026). Sudan Atlas: official names, P-codes and boundaries for Sudan's states and localities. Zenodo. https://doi.org/10.5281/zenodo.24191931

Each GitHub release is archived on Zenodo; the "Cite this repository" button on GitHub gives the citation in APA and BibTeX, from CITATION.cff. Please also credit the boundary source: "OCHA (COD-AB Sudan), via HDX".

Help improve it

Found a spelling the matcher misses, or a name that should match differently? Open an issue with the name as written and the place it refers to. Every new spelling is reviewed before it is added.

Licence

  • Code: MIT
  • Boundaries: CC BY 3.0 IGO, derived from OCHA's COD-AB (details)
  • Gazetteer additions (variant spellings, normalisation rules, test cases): CC BY 4.0
  • OpenStreetMap town spellings: ODbL 1.0, © OpenStreetMap contributors. They are kept in their own file (variants_osm.json), so the ODbL covers that file only, not the other data or your matching results (details)
  • Sources are listed in docs/SOURCES.md. Boundary choices are documented in docs/DATA_POLICY.md.

Boundaries are shown for humanitarian, research and practical use and do not imply any opinion on the legal status of any territory.

Made by Amin Shennan.

Source: README.md at commit 5d8e96f

Tools

6

match_place_name

Match a Sudanese place name

Match one state or locality name, in Arabic or English and any spelling, to its official P-code. Returns pcode (null when not confident), names, score 0-1, method (exact, variant, fuzzy, ambiguous, none) and up to three alternatives.

Parametersnamerequiredlevelstate_hint

match_place_names

Match many Sudanese place names

Match up to 1,000 names at once (for example a spreadsheet column). Each item can carry its own state hint. Results are in the same order as the input.

Parameterslevelnamesrequired

search_places

Search Sudan's states and localities

Find states and localities whose official English or Arabic name contains the text, best first, with the matcher's answer for misspellings.

Parameterslimitqueryrequired

get_place

Details of a state or locality

Official names, level, parent state, localities (for a state), area in km² and estimated population (COD-PS 2025, mid-2025) for a P-code.

Parameterspcoderequired

list_places

List states or localities

All 19 admin-1 units (18 states and the Abyei PCA area), or the localities of the whole country or of one state.

Parameterslevelrequiredstate_pcode

get_boundary

Boundary of a state or locality

The boundary as a GeoJSON Feature (EPSG:4326) with the place's properties. 'light' is small and enough for most maps; 'medium' is more detailed.

Parameterspcoderequiredresolution

Version history

2
  1. v0.1.5LatestNov 22, 2026
  2. v0.1.4Nov 20, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Atlas integrations