API

RusPostIndex

A Russian postal code directory with individual and batch lookups. Served from a local snapshot, with daily checks against the official source.

JSONNo API key requiredUTF-8

Quick start

Base URL: https://lib.studio-k.digital/ruspostindex

curl https://lib.studio-k.digital/ruspostindex/v1/postcodes/199151

View the response →

Successful lookups return data and dataset_version. Send postal codes as six-digit strings. Original place names remain in Russian.

Endpoints

Paths below are relative to the base URL.

Method & path	Description
`GET /v1/postcodes/{index}`	Look up one postal code. Returns 404 if not found.
`POST /v1/postcodes/lookup`	Look up 1–100 codes. Missing records return `data: null`.
`GET /v1/offices`	List offices, 100 per page. Filters: region, city, offset.
`GET /v1/dataset`	Source, dataset date, version, record count and update status.
`GET /health`	API and database availability.

Batch lookup

curl -X POST \
  https://lib.studio-k.digital/ruspostindex/v1/postcodes/lookup \
  -H 'Content-Type: application/json' \
  -d '{"postcodes":["199151","101000","000000"]}'

Results follow the input order. Use strings, not numbers. Empty lists and lists longer than 100 codes return HTTP 400.

Filters & pagination

curl -G https://lib.studio-k.digital/ruspostindex/v1/offices \
  --data-urlencode 'region=МОСКВА' \
  --data-urlencode 'offset=0'

Filters match original values exactly, usually in uppercase. Use offset=100 for the next page, then 200. Results are ordered by postal code.

CITY may be empty: a city name can appear in REGION instead.

Response fields

Field	Meaning
`INDEX`	Postal code.
`OPSNAME`, `OPSTYPE`	Postal facility name and type.
`OPSSUBM`	Postal code of the parent facility.
`REGION`, `AUTONOM`, `AREA`	Region, autonomous area and district.
`CITY`, `CITY_1`	Locality and subordinate locality.
`ACTDATE`	Record modification date (YYYYMMDD), not the date of the full dataset.
`INDEXOLD`	Previous postal code, when provided.

Errors & limits

400 invalid input · 404 record or route not found · 429 rate limit exceeded · 503 dataset unavailable · 500 internal error.

Limit: 20 requests per second per IP, with a burst allowance of 40. Infrastructure errors may return HTML. Browser cross-origin access (CORS) is not enabled; call the API from your server.

A listed code does not guarantee delivery availability. This directory does not include street-to-house coverage, opening hours or telephone numbers. A missing record means it was not found in the current snapshot.

Data & attribution

Data source: Russian Post’s official postal directory. Updates are checked daily; source outages leave the last validated snapshot available.

Inspect the current dataset →

Developed and operated by Studio K. Application responses include X-Service-Provider: studio-k.digital.