List Cities

Retrieve a list of all cities with optional filtering by country, state, and other criteria.

HTTP Request

GET/api/locations/cities

Authorization

Authorization

• Required: Yes
• Permission: Admin or Staff
• Authentication: Token-based (Authorization: Token <your_api_key>)

Query Parameters

Parameter	Type	Default	Description
limit	integer	—	Number of results to return per page
offset	integer	—	Number of results to skip before returning results
search	string	—	Search term to filter results by `id`, `name` and `code`
ordering	string	—	Field to order results by (`id`, `active`, `name`, `code`, `state`)
country_id	integer	—	Filter cities by country ID
country_in	string	—	Filter cities by multiple country IDs (comma-separated: 1,2,3)
state_id	integer	—	Filter cities by state ID
state_in	string	—	Filter cities by multiple state IDs (comma-separated: 1,2,3)
active	boolean	—	Filter by active status

Example Requests

🐍 Python

1import requests
2
3url = "https://api.example.com/api/locations/cities"
4headers = {
5  "Authorization": "Token <your_api_key>"
6}
7params = {
8  "limit": 10,
9  "offset": 0,
10  "search": "Los Angeles"
11}
12response = requests.get(url, headers=headers, params=params)
13print(response.json())

🌐 Curl

1curl -X GET "https://api.example.com/api/locations/cities?limit=10&offset=0&search=Los%20Angeles" \
2-H "Authorization: Token <your_api_key>"

Status Codes

Code	Description
200	Successfully retrieved cities list
400	Invalid query parameters
401	Authentication required
403	Insufficient permissions
500	Server error occurred

Response Fields

Field	Type	Description
id	integer	Unique city identifier
name	string	City name
code	string	City code (e.g., 'LA')
state	object	State information

State Object Fields:

Field	Type	Description
id	integer	Unique state identifier
name	string	State name
code	string	State code