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

string

No

Inclusion

filter[<filter_name>]

string, boolean

No

Filtering

fields[cities]

string

No

Sparse fieldsets

sort

string

No

Sorting

page[number]

integer

No

Page number.

page[size]

integer

No

Page size. Pagination defaults to 1000 records per page. The maximum is 1000.

Includes#

Value

Description

country

Country Object

region

Region Object

area

Area Object

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#

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}

Other Responses#

Code

Success

Description

400

No

Bad Request

401

No

Unauthorized

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.