> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/address/geographic-data.md).

# Geographic Data

Countries, cities, townships, districts (public)

## List Countries

> Get all available countries.

```json
{"openapi":"3.0.3","info":{"title":"Address API","version":"1.0.0"},"tags":[{"name":"Geographic Data","description":"Countries, cities, townships, districts (public)"}],"servers":[{"description":"Server base URL for address operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/address/country/":{"get":{"tags":["Geographic Data"],"summary":"List Countries","description":"Get all available countries.","operationId":"listCountries","parameters":[{"$ref":"#/components/parameters/PageParameter"},{"$ref":"#/components/parameters/PageSizeParameter"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"responses":{"200":{"description":"List of countries","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"next":{"type":"string","format":"uri","nullable":true},"previous":{"type":"string","format":"uri","nullable":true},"results":{"type":"array","items":{"$ref":"#/components/schemas/Country"}}}}}}}}}}},"components":{"parameters":{"PageParameter":{"name":"page","in":"query","description":"Page number (starts from 1)","required":false,"schema":{"type":"integer","minimum":1,"default":1}},"PageSizeParameter":{"name":"page_size","in":"query","description":"Number of records per page","required":false,"schema":{"type":"integer","minimum":1,"default":10}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"Country":{"type":"object","properties":{"pk":{"type":"integer"},"is_active":{"type":"boolean"},"name":{"type":"string"},"code":{"type":"string","description":"ISO 3166-1 alpha-2 code"},"translations":{"type":"object","nullable":true}}}}}}
```

## List Cities

> Get cities, optionally filtered by country.

```json
{"openapi":"3.0.3","info":{"title":"Address API","version":"1.0.0"},"tags":[{"name":"Geographic Data","description":"Countries, cities, townships, districts (public)"}],"servers":[{"description":"Server base URL for address operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/address/city/":{"get":{"tags":["Geographic Data"],"summary":"List Cities","description":"Get cities, optionally filtered by country.","operationId":"listCities","parameters":[{"name":"country","in":"query","description":"Country ID","schema":{"type":"integer"}},{"$ref":"#/components/parameters/PageParameter"},{"$ref":"#/components/parameters/PageSizeParameter"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"responses":{"200":{"description":"List of cities","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"next":{"type":"string","format":"uri","nullable":true},"previous":{"type":"string","format":"uri","nullable":true},"results":{"type":"array","items":{"$ref":"#/components/schemas/City"}}}}}}}}}}},"components":{"parameters":{"PageParameter":{"name":"page","in":"query","description":"Page number (starts from 1)","required":false,"schema":{"type":"integer","minimum":1,"default":1}},"PageSizeParameter":{"name":"page_size","in":"query","description":"Number of records per page","required":false,"schema":{"type":"integer","minimum":1,"default":10}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"City":{"type":"object","properties":{"pk":{"type":"integer"},"is_active":{"type":"boolean"},"name":{"type":"string"},"country":{"type":"integer","description":"Country ID"},"translations":{"type":"object","nullable":true},"priority":{"type":"integer"},"postcode":{"type":"string","nullable":true}}}}}}
```

## Get City Details

> View details of a specific city.

```json
{"openapi":"3.0.3","info":{"title":"Address API","version":"1.0.0"},"tags":[{"name":"Geographic Data","description":"Countries, cities, townships, districts (public)"}],"servers":[{"description":"Server base URL for address operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/address/city/{pk}/":{"get":{"tags":["Geographic Data"],"summary":"Get City Details","description":"View details of a specific city.","operationId":"getCity","parameters":[{"name":"pk","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"responses":{"200":{"description":"City details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/City"}}}},"404":{"description":"City not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}}}},"components":{"parameters":{"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"City":{"type":"object","properties":{"pk":{"type":"integer"},"is_active":{"type":"boolean"},"name":{"type":"string"},"country":{"type":"integer","description":"Country ID"},"translations":{"type":"object","nullable":true},"priority":{"type":"integer"},"postcode":{"type":"string","nullable":true}}}}}}
```

## Search Cities

> Search cities by name (minimum 2 characters).\
> \
> \*\*Note\*\*: Query parameter \`q\` is mapped internally to \`name\`.

```json
{"openapi":"3.0.3","info":{"title":"Address API","version":"1.0.0"},"tags":[{"name":"Geographic Data","description":"Countries, cities, townships, districts (public)"}],"servers":[{"description":"Server base URL for address operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/address/city/search/":{"get":{"tags":["Geographic Data"],"summary":"Search Cities","description":"Search cities by name (minimum 2 characters).\n\n**Note**: Query parameter `q` is mapped internally to `name`.","operationId":"searchCities","parameters":[{"name":"q","in":"query","required":true,"description":"City name to search (minimum 2 characters)","schema":{"type":"string","minLength":2}},{"name":"country","in":"query","description":"Filter by country ID","schema":{"type":"integer"}},{"$ref":"#/components/parameters/PageParameter"},{"$ref":"#/components/parameters/PageSizeParameter"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"responses":{"200":{"description":"Matching cities","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"next":{"type":"string","format":"uri","nullable":true},"previous":{"type":"string","format":"uri","nullable":true},"results":{"type":"array","items":{"$ref":"#/components/schemas/City"}}}}}}},"400":{"description":"Query too short (minimum 2 characters)","content":{"application/json":{"schema":{"type":"object","properties":{"field_name":{"type":"array","items":{"type":"string"}}}}}}}}}}},"components":{"parameters":{"PageParameter":{"name":"page","in":"query","description":"Page number (starts from 1)","required":false,"schema":{"type":"integer","minimum":1,"default":1}},"PageSizeParameter":{"name":"page_size","in":"query","description":"Number of records per page","required":false,"schema":{"type":"integer","minimum":1,"default":10}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"City":{"type":"object","properties":{"pk":{"type":"integer"},"is_active":{"type":"boolean"},"name":{"type":"string"},"country":{"type":"integer","description":"Country ID"},"translations":{"type":"object","nullable":true},"priority":{"type":"integer"},"postcode":{"type":"string","nullable":true}}}}}}
```

## List Townships

> Get townships (districts of cities), optionally filtered by city.

```json
{"openapi":"3.0.3","info":{"title":"Address API","version":"1.0.0"},"tags":[{"name":"Geographic Data","description":"Countries, cities, townships, districts (public)"}],"servers":[{"description":"Server base URL for address operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/address/township/":{"get":{"tags":["Geographic Data"],"summary":"List Townships","description":"Get townships (districts of cities), optionally filtered by city.","operationId":"listTownships","parameters":[{"name":"city","in":"query","description":"City ID","schema":{"type":"integer"}},{"$ref":"#/components/parameters/PageParameter"},{"$ref":"#/components/parameters/PageSizeParameter"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"responses":{"200":{"description":"List of townships","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"next":{"type":"string","format":"uri","nullable":true},"previous":{"type":"string","format":"uri","nullable":true},"results":{"type":"array","items":{"$ref":"#/components/schemas/Township"}}}}}}}}}}},"components":{"parameters":{"PageParameter":{"name":"page","in":"query","description":"Page number (starts from 1)","required":false,"schema":{"type":"integer","minimum":1,"default":1}},"PageSizeParameter":{"name":"page_size","in":"query","description":"Number of records per page","required":false,"schema":{"type":"integer","minimum":1,"default":10}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"Township":{"type":"object","properties":{"pk":{"type":"integer"},"is_active":{"type":"boolean"},"name":{"type":"string"},"city":{"type":"integer","description":"City ID"},"postcode":{"type":"string","nullable":true},"translations":{"type":"object","nullable":true}}}}}}
```

## List Districts

> Get districts (neighborhoods), optionally filtered by township.

```json
{"openapi":"3.0.3","info":{"title":"Address API","version":"1.0.0"},"tags":[{"name":"Geographic Data","description":"Countries, cities, townships, districts (public)"}],"servers":[{"description":"Server base URL for address operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/address/district/":{"get":{"tags":["Geographic Data"],"summary":"List Districts","description":"Get districts (neighborhoods), optionally filtered by township.","operationId":"listDistricts","parameters":[{"name":"township","in":"query","description":"Township ID","schema":{"type":"integer"}},{"$ref":"#/components/parameters/PageParameter"},{"$ref":"#/components/parameters/PageSizeParameter"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"responses":{"200":{"description":"List of districts","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"next":{"type":"string","format":"uri","nullable":true},"previous":{"type":"string","format":"uri","nullable":true},"results":{"type":"array","items":{"$ref":"#/components/schemas/District"}}}}}}}}}}},"components":{"parameters":{"PageParameter":{"name":"page","in":"query","description":"Page number (starts from 1)","required":false,"schema":{"type":"integer","minimum":1,"default":1}},"PageSizeParameter":{"name":"page_size","in":"query","description":"Number of records per page","required":false,"schema":{"type":"integer","minimum":1,"default":10}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"District":{"type":"object","properties":{"pk":{"type":"integer"},"is_active":{"type":"boolean"},"name":{"type":"string"},"city":{"type":"integer","description":"City ID"},"township":{"type":"integer","description":"Township ID"},"postcode":{"type":"string","nullable":true},"translations":{"type":"object","nullable":true}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://apidocs.akinon.com/commerce-openapis/address/geographic-data.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.