# 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.