REST reference
Versioned REST endpoints for countries, subdivisions, places, search, and reverse geocoding.
The hosted REST API exposes the same canonical snapshot as the npm package under /api/v1.
The hosted layer is an opt-in product surface. The open dataset and downloadable npm package remain available independently.
Authentication
Pass an API key in the x-api-key header. /api, /api/v1/health, /api/openapi.json, and /api/policy.json are public; data and GraphQL routes fail closed when authentication is not configured.
curl 'https://countrystatecity.tansuasici.com/api/v1/subdivisions?country=TR&limit=5' \
-H 'x-api-key: YOUR_API_KEY'Keep API keys on the server. The hosted service stores only SHA-256 hashes and logs only the configured key identifier.
REST endpoints
| Method | Route | Purpose |
|---|---|---|
GET | /api/v1/countries | Countries with search, pagination, and field selection |
GET | /api/v1/countries/:code | Country by ISO-2, ISO-3, or numeric id |
GET | /api/v1/subdivisions?country=TR | First-level administrative areas |
GET | /api/v1/places?country=TR&subdivision=34 | Places scoped to a country and subdivision |
GET | /api/v1/search?q=Kadikoy | Cross-entity search |
GET | /api/v1/reverse?latitude=40.9811&longitude=29.0651 | Nearest centres and optional Türkiye polygon lookup |
POST | /api/v1/reverse/batch | Batch nearest-centre lookup for up to 1,000 points |
GET | /api/v1/health | Public service health and dataset counts |
limit defaults to 25 and is capped at 100. Use offset for pagination and fields=id,name,iso2 to request a REST field subset.
Search requires at least two characters. types accepts country, subdivision, place, and district.
Reverse geocoding
curl 'https://countrystatecity.tansuasici.com/api/v1/reverse?latitude=40.9811&longitude=29.0651&country=TR' \
-H 'x-api-key: YOUR_API_KEY'Nearest-centre responses include haversine distance and center-distance confidence. They do not
claim containment. Add polygon=true for point-in-polygon results where versioned boundaries
exist; current polygon coverage is Türkiye admin-1/admin-2. See Reverse geocoding.
Version and cache contract
Every data response includes meta.apiVersion, meta.dataVersion, and meta.source. GraphQL responses carry the same values in extensions.meta. ETag/If-None-Match, Cache-Control, X-Cache, and X-Data-Version support conditional and observable caching.
Breaking schema changes use a new major URL version. A deprecated version receives at least 180 days notice through documentation plus Deprecation, Sunset, and Link headers.
For authentication, quotas, payload limits, caching, and deprecation behavior, see
Limits & policy. The machine-readable REST contract is available at
/api/openapi.json.