Sudan Atlas

io.github.aminshennan由 GitHub 账号 aminshennan 发布v0.1.5更新于 Nov 22, 2026

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

发布方自己的服务:Red Atlas Api

已验证Streamable HTTP可网页运行位置与生活数据与分析

概览

AI 生成的概览

将阿拉伯语或英语的苏丹地名匹配为官方 P-code,并返回名称、人口估计与 GeoJSON 边界。

可以做什么
  • 将单个地名或最多 1000 个地名批量匹配为官方 P-code,附置信度与候选结果
  • 按英文或阿拉伯语部分名称搜索州与地方行政区
  • 按 P-code 查询官方名称、层级、所属州、面积与估计人口
  • 列出全部 19 个一级行政区,或全国及某一州的地方行政区
  • 获取某地的 GeoJSON 边界要素,可选轻量或中等精度
适用场景
适合处理苏丹行政区划数据:在制图或与其他人道主义数据集关联前清洗地名表格,或查询州与地方行政区的官方名称、代码、人口和边界。
运行要求
远程 MCP 端点,使用 streamable HTTP;无需账号、密钥或本地运行环境。README 说明每个地址每分钟最多 60 次请求。
安装前请注意
发送的地名会在服务器上处理(网站称不存储、不记录日志)。匹配可能出错或存在歧义:置信度低时 P-code 为 null 并返回候选,应由人来判断。人口为 2025 年中期估计值而非统计数,边界不代表对任何领土法律地位的立场。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Sudan Atlas,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable,通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

交给智能体安装

把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体,或 SourceWeft 对话中。智能体会读取该服务器的安装指南,先向你展示发布者、端点和登录方式,经你同意后再把它添加到你的客户端。密钥不会写进任何命令。

阅读 https://sourceweft.com/mcp/io.github.aminshennan%2Fsudan-atlas/install.md,并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前,先告诉我它的发布者、端点和登录方式,等我确认。不要把 API 密钥写进命令或我会提交的文件;问我密钥应从哪里获取。

查看智能体所依据的安装指南

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

{
  "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.

来源:README.md,提交 5d8e96f

工具

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.

输入参数name必填levelstate_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.

输入参数levelnames必填

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.

输入参数limitquery必填

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.

输入参数pcode必填

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.

输入参数level必填state_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.

输入参数pcode必填resolution

版本历史

2
  1. v0.1.5最新Nov 22, 2026
  2. v0.1.4Nov 20, 2026

评分

已满足适用检查项的 100%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分
  • 已声明认证方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

其他 Atlas 集成