Important! This API is for OpenWeatherMap cities. ☀️
When our team decided to develop this API, the problem was in the point , that OpenWeartherMap API hasn't provided a possibility to get all cities by request. They propose to get cities only from the big 29mbs json file called city.list.json . If you use their's API for web or desktop apps - it's ok, you can store this file.In other cases, e.g. when you develop a mobile app, it isn't a good idea to store 29mbs file on a mobile device.So you need to have an API, that can give you some cities by request. Using weatherGetCitiesAPI you can get all cities, get cities by name in some different ways and control fields & count of requested cities.
We hope that this API will help you )
URL:
http://cities.vsx2.com/api?mode={mode_code}&q={query_string}
You can pass some Additional params
-
mode (type Integer)
- mode = 0 "Start with" search
- mode = 1 "Contains" search
-
query (type String)
- fields (type String)
- name
- id
- country
- coord
You can combine fields. Default fields=name,id
- limit (type Integer) - limit of cities in response, e.g you can get only 5 cities that contains 'ab'
items - result array of objects // If cities were not found, items will be an empty array
errors - array of strings, where string is an error description
- List of errors:
-
Invalid mode
-
Empty Query
-
Invalid limit
-
Invalid field
-
status - status of request
- List of statuses:
-
success
-
error
-
total_items - count of found cities in cities.list.json by query (type Integer)
{"errors": [], "items": [{"name": "Oradell", "id": 5102208}], "status": "success", "total_items": 1}
URL:
http://cities.vsx2.com/api?mode=0&q=Rio De J
Response:
{
"errors": [],
"items": [
{
"name": "Rio de Janeiro",
"id": 3451190
},
{
"name": "Rio de Jesus",
"id": 3701882
}
],
"status": "success",
"total_items": 1
}
Response:
{
"errors": [],
"items": [
{
"name": "Rio de Janeiro",
"id": 3451190
}
],
"status": "success",
"total_items": 1
}
URL:
http://cities.vsx2.com/api?mode=0&q=Khark&fields=name
Response:
{
"errors": [],
"items": [
{
"name": "Kharkiv"
},
{
"name": "Kharkivs’ka Oblast’"
},
{
"name": "Kharkhorin"
},
{
"name": "Kharkhauda"
},
{
"name": "Kharkhauda"
}
],
"status": "success",
"total_items": 4
}
URL:
http://cities.vsx2.com/api?mode=0&q=Khark&limit=2
Response:
{
"errors": [],
"items": [
{
"name": "Kharkiv",
"id": 706483
},
{
"name": "Kharkivs’ka Oblast’",
"id": 706482
}
],
"status": "success",
"total_items": 4
}
URL:
http://cities.vsx2.com/api?mode=1&q=ord&limit=2&fields=name,country
Response:
{
"errors": [],
"items": [
{
"name": "Portman",
"country": "ES"
},
{
"name": "Groveport",
"country": "US"
},
{
"name": "East Porterville",
"country": "US"
},
{
"name": "Port Stephens",
"country": "AU"
},
{
"name": "Cotiporã",
"country": "BR"
}
],
"status": "success",
"total_items": 846
}