Schemas

This page summarizes the shared v2 response envelopes and resource schemas. Field-level details for settlement resources are also documented on their dedicated reference pages.

Response Envelopes

Data Response

Single-resource endpoints return:

{
  "data": {},
  "meta": {
    "datasetVersion": "2025",
    "lastUpdated": "2026-05-21"
  }
}

List Response

List endpoints return:

{
  "data": [],
  "meta": {
    "count": 0,
    "total": 0,
    "limit": 100,
    "offset": 0,
    "datasetVersion": "2025",
    "lastUpdated": "2026-05-21"
  }
}

Field	Type	Description
meta.count	integer	Number of records in the current response
meta.total	integer	Number of records matching the filters
meta.limit	integer	Requested page size
meta.offset	integer	Requested offset
meta.datasetVersion	string	Dataset version used by the response
meta.lastUpdated	string	Dataset update date

Resource Schemas

Schema	Description	Reference
Province	Province record with geography, region, coordinates, and aggregate counts	Provinces
District	District record with parent province, area, population, and aggregate counts	Districts
Municipality	Municipality record with type, parent IDs, population, and neighborhood count	Municipalities
Neighborhood	Neighborhood record with parent IDs, population, postal code, and postal code status	Neighborhoods
Village	Village record with parent IDs, population, postal code, and postal code status	Villages

Shared Field Types

Field pattern	Type	Notes
id	integer	Positive resource ID
name	string	Human-readable Turkish name
slug	string	URL-safe resource name
population	integer	Non-negative population
area.value	number	Area value
area.unit	string	Always km2
altitude.value	number	Altitude value
altitude.unit	string	Always m
postalCode	string	Five-digit postal code
postalCodeStatus	string	Postal code status. Neighborhoods use official, derived, or estimated; villages use official or estimated
stats.*Count	integer	Non-negative aggregate count

postalCodeStatus distinguishes values used directly from official PTT postal code data (official), neighborhood-only values derived from a previous settlement with a known PTT postal code (derived), and values inferred from supplementary public sources, nearby settlements, district-level patterns, or administrative-change records (estimated). Clients that require strict official postal code data should filter records where postalCodeStatus is official.

stats.*Count values are derived from the indexed relationships in the loaded dataset. They match the child records served by the corresponding nested collection endpoints.

Municipality Types

Value	Meaning
province_center	Province center municipality
district_center	District center municipality
town	Town municipality

Meta Schema

GET /v2/meta returns:

Field	Type	Description
apiVersion	string	API version
datasetVersion	string	Dataset version
lastUpdated	string	Dataset update date
sources	array	Dataset source list
counts.provinces	integer	Province count
counts.districts	integer	District count
counts.municipalities	integer	Municipality count
counts.neighborhoods	integer	Neighborhood count
counts.villages	integer	Village count

The counts.* values are derived from the loaded dataset records.

Error Schema

Error responses use:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Error message.",
    "status": 400
  }
}

See Errors for error codes and examples.