Get Cities#
Returns a list of cities. Maximum page size is 1000. Default page size is 1000.
Request#
HTTP Method: GET
URI Path: /v3/cities
Note
For all returned data attributes, see City Object.
URI Query Parameters#
Name |
Type |
Is Required? |
Description |
|---|---|---|---|
include |
|
No |
|
filter[<filter_name>] |
|
No |
|
fields[cities] |
|
No |
|
sort |
|
No |
|
page[number] |
|
No |
|
page[size] |
|
No |
Page size. Pagination defaults to |
Includes#
Value |
Description |
|---|---|
country |
|
region |
|
area |
Filters#
Filter Name |
Type |
Allow Blank |
Allow Array |
Filters by: |
|---|---|---|---|---|
id |
|
No |
Yes |
City |
name |
|
Yes |
Yes |
City |
country.id |
|
Yes |
Yes |
A |
region.id |
|
Yes |
Yes |
A |
is_available |
|
No |
No |
Indicates if DID numbers in the specified city are currently available for purchase |
area.id |
|
Yes |
Yes |
A |
Sorting#
Value |
Sort by |
|---|---|
name |
City |
Examples#
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}
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}
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}
Other Responses#
Code |
Success |
Description |
|---|---|---|
400 |
No |
|
401 |
No |
|
429 |
No |
The request budget of the account for the current window is spent ( |