Worldviews and disputed areas

Some areas have a different country on the maps of different countries, such as Kashmir or Western Sahara. Users expect the country of their own maps. For example, users in India expect Muzaffarabad in India, and users in Pakistan expect it in Pakistan. The worldview parameter selects the country of these cities.

curl "https://api.onde.earth/v1/cities/search?q=muzaffarabad&worldview=in" \
  -H "Authorization: Bearer $ONDE_KEY"

With worldview=in, Muzaffarabad has the country IN. With the default worldview, it has PK. The default worldview is us. Worldviews in the API reference lists each worldview and each value that it changes.

Country codes, country names, and the disputed field are not a political position.

Select a worldview

Use the worldview of the country of your users. If your users are in many countries, select the worldview for each user, for example from the country of the account.

Send the same worldview in all requests for one user. Then the country of each city agrees with the list of countries and with the country filter.

If you store country with a city, also store the worldview of the request.

Which cities move

A worldview moves a city in a disputed area to the country that the worldview gives the area. The worldview moves a city only if the city has the country of the us worldview. If the sources give a city different countries, the city keeps its country in all worldviews.

If a worldview gives all of a country to a different country, the worldview removes the country from the list of countries. All cities of the removed country move.

When a worldview moves a city, region is null, because each region belongs to a country of the default worldview.

The rs worldview is equal to the us worldview, except for Kosovo.

Country codes

In the default worldview, country.code is the ISO 3166-1 alpha-2 code of the country. Kosovo has the code XK, because many systems use this code. XK is not an ISO 3166-1 code.

The disputed field

disputed is true for a city in an area on a published list of disputed areas. The worldview does not change disputed. Use disputed to find the cities that can need a worldview.

isCapital follows the source data. A contested capital has isCapital false.