Get Cities

Description

Returns a list of cities. Maximum page size is 1000. Default page size is 1000.

Request

HTTP Method: GET

URI Path: /v3/cities

URI Query Parameters:

Name

Type

Is Required?

Description

filter[<filter_name>]

integer

Optional

Filtering

includes

string

Optional

Inclusion

sort

string

Optional

Sorting

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.

country.id

integer

Yes

Yes

A country.id field.

region.id

integer

Yes

Yes

A region.id field.

is_available

boolean

No

No

When true, shows cities which have DID groups in coverage with DID numbers available for purchase. When false shows cities which have DID groups without DID numbers available for purchase.

area.id

integer

Yes

Yes

A area.id field.

Sorting:

Value

Sorts by:

name

City name field.

Examples

http

GET /v3/cities HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API Token]

curl

curl -i https://api.didww.com/v3/cities -H 'Accept: application/vnd.api+json' -H 'Api-Key: [API Token]' -H 'Content-Type: application/vnd.api+json'

response

HTTP/2 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "dccb89ba-f777-4128-b99b-b25e19ccf4ea",
      "type": "cities",
      "attributes": {
        "name": "Aachen"
      },
      "relationships": {
        "country": {
          "links": {
            "self": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/relationships/country",
            "related": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/country"
          }
        },
        "region": {
          "links": {
            "self": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/relationships/region",
            "related": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/region"
          }
        },
        "area": {
          "links": {
            "self": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/relationships/area",
            "related": "https://api.didww.com/v3/cities/dccb89ba-f777-4128-b99b-b25e19ccf4ea/area"
          }
        }
      }
    }
  ]
}

http

GET /v3/cities?filter%5Bname%5D=Springfield&filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8 HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API Token]

curl

curl -i '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 'Api-Key: [API Token]' -H 'Content-Type: application/vnd.api+json'

response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "79c1ee51-a2dd-4fb2-8c08-ab9120909118",
      "type": "cities",
      "attributes": {
        "name": "Springfield"
      },
      "relationships": {
        "country": {
          "links": {
            "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/country",
            "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/country"
          }
        },
        "region": {
          "links": {
            "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/region",
            "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/region"
          }
        },
        "area": {
          "links": {
            "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/area",
            "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/area"
          }
        }
      }
    }
  ]
}

http

GET /v3/cities?include=country HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API Token]

curl

curl -i 'https://api.didww.com/v3/cities?include=country' -H 'Accept: application/vnd.api+json' -H 'Api-Key: [API Token]' -H 'Content-Type: application/vnd.api+json'

response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "79c1ee51-a2dd-4fb2-8c08-ab9120909118",
      "type": "cities",
      "attributes": {
        "name": "Springfield"
      },
      "relationships": {
        "country": {
          "links": {
            "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/country",
            "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/country"
          }
        },
        "region": {
          "links": {
            "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/region",
            "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/region"
          }
        },
        "area": {
          "links": {
            "self": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/relationships/area",
            "related": "https://api.didww.com/v3/cities/79c1ee51-a2dd-4fb2-8c08-ab9120909118/area"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "3b11ad09-dc7e-451a-9d32-ae9c1604aaa8",
      "type": "countries",
      "attributes": {
        "name": "United States",
        "prefix": "1",
        "iso": "US"
      }
    }
  ]
}

Other Responses

Code

Success

Description

404

No

Not Found

401

No

Unauthorized