# Get Cities

Returns a list of cities. Maximum [page size](../../../specification/pagination.html#api-pagination) is 1000. Default
page size is 1000.

## Request

HTTP Method: `GET`

URI Path: `/v3/cities`

Note

For all returned data attributes, see [City Object](city-object.html).

### URI Query Parameters

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| include | `string` | No | [Inclusion](../../../specification/includes.html#api-includes) |
| filter[<filter\_name>] | `string`, `boolean` | No | [Filtering](../../../specification/filtering.html#api-filters) |
| fields[cities] | `string` | No | [Sparse fieldsets](../../../specification/sparse-fieldsets.html#api-sparse-fieldsets) |
| sort | `string` | No | [Sorting](../../../specification/sorting.html#api-sorting) |
| page[number] | `integer` | No | [Page number](../../../specification/pagination.html#api-pagination). |
| page[size] | `integer` | No | [Page size](../../../specification/pagination.html#api-pagination). Pagination defaults to `1000` records per page. The maximum is `1000`. |

### Includes

| Value | Description |
| --- | --- |
| country | [Country Object](../countries/country-object.html#country-object-v35) |
| region | [Region Object](../regions/region-object.html#region-object-v35) |
| area | [Area Object](../../regulation-resources/areas/area-object.html#area-object-v35) |

### Filters

| Filter Name | Type | Allow Blank | Allow Array | Filters by: |
| --- | --- | --- | --- | --- |
| id | `string` | No | Yes | City `id` field. |
| name | `string` | Yes | Yes | City `name` field. Case insensitive. |
| country.id | `string` | Yes | Yes | A `country.id` field. |
| region.id | `string` | Yes | Yes | A `region.id` field. |
| is\_available | `boolean` | No | No | Indicates if DID numbers in the specified city are currently available for purchase |
| area.id | `string` | Yes | Yes | A `area.id` field. |

### Sorting

| Value | Sort by |
| --- | --- |
| name | City `name` field. |

## Examples

Simple requestFilter by name or country.idInclude Country Resource

[[DIDWW-API-EXAMPLE-START]]

http

```
1GET /v3/cities HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
```

curl

```
1curl -i -X GET https://api.didww.com/v3/cities -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"
```

response

```
 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": [
 6    {
 7      "id": "dccb89ba-f777-4128-b99b-b25e19ccf4ea",
 8      "type": "cities",
 9      "attributes": {
10        "name": "Aachen"
11      },
12      "relationships": {
13        "country": {
14          "links": {
15            "self": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/relationships/country",
16            "related": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/country"
17          }
18        },
19        "region": {
20          "links": {
21            "self": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/relationships/region",
22            "related": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/region"
23          }
24        },
25        "area": {
26          "links": {
27            "self": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/relationships/area",
28            "related": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/area"
29          }
30        }
31      }
32    }
33  ],
34  "meta": {
35    "total_records": 1,
36    "api_version": "2026-11-19"
37  },
38  "links": {
39    "first": "https://api.didww.com/v3/cities?page%5Bnumber%5D=1&page%5Bsize%5D=1000",
40    "last": "https://api.didww.com/v3/cities?page%5Bnumber%5D=1&page%5Bsize%5D=1000"
41  }
42}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
1GET /v3/cities?filter%5Bname%5D=Springfield&filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8 HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
```

curl

```
1curl -i -X GET 'https://api.didww.com/v3/cities?filter%5Bname%5D=Springfield&filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8' -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"
```

response

```
 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": [
 6    {
 7      "id": "79c1ee51-a2dd-4fb2-8c08-ab9120909118",
 8      "type": "cities",
 9      "attributes": {
10        "name": "Springfield"
11      },
12      "relationships": {
13        "country": {
14          "links": {
15            "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/country",
16            "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/country"
17          }
18        },
19        "region": {
20          "links": {
21            "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/region",
22            "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/region"
23          }
24        },
25        "area": {
26          "links": {
27            "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/area",
28            "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/area"
29          }
30        }
31      }
32    }
33  ],
34  "meta": {
35    "total_records": 1,
36    "api_version": "2026-11-19"
37  },
38  "links": {
39    "first": "https://api.didww.com/v3/cities?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bname%5D=Springfield&page%5Bnumber%5D=1&page%5Bsize%5D=1000",
40    "last": "https://api.didww.com/v3/cities?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bname%5D=Springfield&page%5Bnumber%5D=1&page%5Bsize%5D=1000"
41  }
42}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
1GET /v3/cities?include=country HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
```

curl

```
1curl -i -X GET 'https://api.didww.com/v3/cities?include=country' -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"
```

response

```
 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": [
 6    {
 7      "id": "79c1ee51-a2dd-4fb2-8c08-ab9120909118",
 8      "type": "cities",
 9      "attributes": {
10        "name": "Springfield"
11      },
12      "relationships": {
13        "country": {
14          "links": {
15            "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/country",
16            "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/country"
17          },
18          "data": {
19            "type": "countries",
20            "id": "3b11ad09-dc7e-451a-9d32-ae9c1604aaa8"
21          }
22        },
23        "region": {
24          "links": {
25            "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/region",
26            "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/region"
27          }
28        },
29        "area": {
30          "links": {
31            "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/area",
32            "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/area"
33          }
34        }
35      }
36    }
37  ],
38  "included": [
39    {
40      "id": "3b11ad09-dc7e-451a-9d32-ae9c1604aaa8",
41      "type": "countries",
42      "attributes": {
43        "name": "United States",
44        "prefix": "1",
45        "iso": "US"
46      },
47      "relationships": {
48        "regions": {
49          "links": {
50            "self": "https://api.didww.com/v3/countries/3b11ad09-dc7e-451a-9d32-ae9c1604aaa8/relationships/regions",
51            "related": "https://api.didww.com/v3/countries/3b11ad09-dc7e-451a-9d32-ae9c1604aaa8/regions"
52          }
53        }
54      }
55    }
56  ],
57  "meta": {
58    "total_records": 1,
59    "api_version": "2026-11-19"
60  },
61  "links": {
62    "first": "https://api.didww.com/v3/cities?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=1000",
63    "last": "https://api.didww.com/v3/cities?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=1000"
64  }
65}
```

[[DIDWW-API-EXAMPLE-END]]

## Other Responses

| Code | Success | Description |
| --- | --- | --- |
| 400 | No | [Bad Request](../../../specification/errors/index.html#api-bad-request) |
| 401 | No | [Unauthorized](../../authentication.html#authentication-v35) |
| 429 | No | The request budget of the account for the current window is spent (`too_many_requests`). `Retry-After` gives the number of seconds to wait. |
