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>] |
|
Optional |
|
include |
|
Optional |
|
sort |
|
Optional |
Includes:
Value |
Description |
|---|---|
country |
|
region |
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 |
Sorting:
Value |
Sorts 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
5Api-Key: [API Token]
curl
1curl -i -X GET 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
1HTTP/2 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 }
26 }
27 ],
28 "meta": {
29 "total_records": 1,
30 "api_version": "2017-09-18"
31 },
32 "links": {
33 "first": "https://api.didww.com/v3/cities?page%5Bnumber%5D=1&page%5Bsize%5D=1000",
34 "last": "https://api.didww.com/v3/cities?page%5Bnumber%5D=2&page%5Bsize%5D=1000"
35 }
36 }
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
5Api-Key: [API 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 "Api-Key: [API Token]" -H "Content-Type: application/vnd.api+json"
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 }
26 }
27 ],
28 "meta": {
29 "total_records": 1,
30 "api_version": "2017-09-18"
31 },
32 "links": {
33 "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",
34 "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"
35 }
36}
http
1GET /v3/cities?include=country HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Api-Key: [API Token]
curl
1curl -i -X GET '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
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 }
26 }
27 ],
28 "included": [
29 {
30 "id": "3b11ad09-dc7e-451a-9d32-ae9c1604aaa8",
31 "type": "countries",
32 "attributes": {
33 "name": "United States",
34 "prefix": "1",
35 "iso": "US"
36 },
37 "relationships": {
38 "regions": {
39 "links": {
40 "self": "https://api.didww.com/v3/countries/3b11ad09-dc7e-451a-9d32-ae9c1604aaa8/relationships/regions",
41 "related": "https://api.didww.com/v3/countries/3b11ad09-dc7e-451a-9d32-ae9c1604aaa8/regions"
42 }
43 }
44 }
45 }
46 ],
47 "meta": {
48 "total_records": 1,
49 "api_version": "2017-09-18"
50 },
51 "links": {
52 "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",
53 "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"
54 }
55}
Other Responses#
Code |
Success |
Description |
|---|---|---|
404 |
No |
|
401 |
No |