Free · Takes two minutes
Get a free API key
All the data is public, and the API works without a key. A key gives you higher limits and a record of how you use the API.
What a key gets you
| Without a key | With a free key | |
|---|---|---|
| Requests a minute | 60 | 600 |
| Requests a day | 5,000 | 100,000 |
| Search and address matching | 20 a minute | 120 a minute |
| Counted against | Your IP address, shared with everyone behind it | Your account, wherever you call from |
| Usage history | None | Requests per day, top endpoints, errors, and every request with a one-click replay |
| Data you can read | Everything | Everything (a key never unlocks extra data) |
How throttling works
Limits keep the API fast and fair for everyone. They are generous for normal use.
Every request counts towards a per-minute and a per-day limit. When either is used up you have to wait for that window to reset.
Without a key, requests are counted per IP address. With a key, they are counted per account, so all your keys share one allowance.
Search and address matching are the most expensive calls, so they have their own lower per-minute limit on top of the general one.
Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get 429 Too Many Requests with a Retry-After header in seconds.
format=csv or format=json instead of paging;
and for complete datasets use the downloads, which do not count at all.
How to get a key
-
1
Create an account
Register with your name and email address.
-
2
Verify your email
Click the link we send you. Keys are only issued to verified accounts.
-
3
Create a key
In your account, open API keys, name the key after the app that will use it, and copy it. It is shown only once.
-
4
Send it with each request
Add the header Authorization: Bearer <your key>. See your usage under API usage.
curl -g -H 'Authorization: Bearer YOUR_KEY' \ 'https://opendata.ssmusoke.dev/api/v1/villages?filter[district]=91&format=json'
$rows = json_decode(file_get_contents('https://opendata.ssmusoke.dev/api/v1/villages?filter[district]=91&format=json', false, stream_context_create([
'http' => ['header' => 'Authorization: Bearer YOUR_KEY'],
])), true);
$rows = Http::withToken('YOUR_KEY')
->get('https://opendata.ssmusoke.dev/api/v1/villages', ['filter' => ['district' => 91], 'format' => 'json'])
->json();
rows = requests.get(
"https://opendata.ssmusoke.dev/api/v1/villages",
params={"filter[district]": 91, "format": "json"},
headers={"Authorization": "Bearer YOUR_KEY"},
).json()
const rows = await fetch("https://opendata.ssmusoke.dev/api/v1/villages?filter[district]=91&format=json", {
headers: { Authorization: "Bearer YOUR_KEY" },
}).then((r) => r.json());