GeoDB Cities API

Why should I care about this?

If you want to return anything interesting about cities to your users beyond the basics, you really should care about WikiData. This is a growing online database that is intended to be the structured-data equivalent to Wikipedia. Using WikiData SPARQL queries, you can enrich the results from the GeoDB Cities API with WikiData information linked to those cities. Here are just a few examples:

• Mayors
• Official Images
• Significant Historical Events
• Tourist Attractions

By leveraging both services, you can combine the quick GeoDB Cities API response time of finding your list of cities with the rich detail view made possible by WikiData.

In plain English, what are we actually trying to do?

In this example, we walk you through how to retrieve tourist attractions for the New York City area.

Got it, what do I need to know before we start?

This tutorial assumes a basic knowledge of:

• WikiData
• SPARQL
• cURL

I'm hooked into a caffeine drip, go on!

To get the WikiData id for New York, we use the GeoDB Find Cities API. For our purposes, we'll set namePrefix=New and minPopulation=1,000,000. That should narrow it down to our single desired result.

curl --get --include 'https://wft-geo-db.p.rapidapi.com/v1/geo/cities?namePrefix=new&minPopulation=1000000' \
    -H 'x-rapidapi-key: YOUR_API_KEY' \
    -H 'x-rapidapi-host: wft-geo-db.p.rapidapi.com'

This gives back the following JSON response:

{
  "data": [
    {
      "id": 105802,
      "wikiDataId": "Q60",
      "city": "New York City",
      "country": "United States of America",
      "countryCode": "US",
      "region": "New York",
      "regionCode": "NY",
      "latitude": 40.71427,
      "longitude": -74.00597
    }
  ],
  "metadata": {
    "currentOffset": 0,
    "totalCount": 1
  }
}

The SPARQL Query

Having obtained the WikiData id for New York (Q60), our SPARQL query can now be formed from the following rule-matching triplets:

• An attraction is an instance of any subclass of a Tourist Attraction.

  ?attraction (wdt:P31/wdt:P279*) wd:Q570116

• An attraction is located in the administrative territorial entity of New York City.

  ?attraction wdt:P131 wd:Q60

• An attraction has a coordinate location of gps.

  ?attraction wdt:P625 ?gps

• An attraction has a label of attractionLabel.

  ?attraction rdfs:label ?attractionLabel

With these triplets, we can now write the full query below (we also include a FILTER constraint on the attractionLabel for English only):

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX wd: <http://www.wikidata.org/entity/>
PREFIX wdt: <http://www.wikidata.org/prop/direct/>

SELECT DISTINCT ?attraction ?attractionLabel ?gps 

WHERE {
    ?attraction (wdt:P31/wdt:P279*) wd:Q570116;
        wdt:P625 ?gps;
        rdfs:label ?attractionLabel.
 
    ?attraction wdt:P131 wd:Q60
            
    FILTER(LANG(?attractionLabel) = "en")
}

You can execute this query directly in WikiData's excellent online Query UI to obtain the following results:

That's it? Why so few results?

WikiData entities tend to refer to very specific things. In particular, as of this writing, there is no native concept of one entity semantically subsuming another. So when you directly ask for all tourist attractions in New York City (Q60), WikiData does not automatically infer that you must also be talking about the borough of Manhattan.

There are two ways to fix this:

1. Update the SPARQL query to add triplet rules for attractions in New York City and all of its boroughs, or:
2. Instead of just getting the WikiData id for New York City, get the ids for ALL cities - large and small - in that area. Then update the SPARQL query to cover attractions in any of these cities.

Let's go with Option 2

To get the WikiData ids for relevant cities in the NYC area, we use the GeoDB Find Cities Near City API with the following parameters:

• cityId=Q60
• radius=10 (miles)
• minPopulation=500000

curl --get --include 'https://wft-geo-db.p.rapidapi.com/v1/geo/cities/Q60/nearbyCities?radius=10&minPopulation=500000' \
    -H 'x-rapidapi-key: YOUR_API_KEY' \
    -H 'x-rapidapi-host: wft-geo-db.p.rapidapi.com'

This gives back the following JSON response:

{
  "data": [
    {
      "id": 105802,
      "wikiDataId": "Q60",
      "city": "New York City",
      "country": "United States of America",
      "countryCode": "US",
      "region": "New York",
      "regionCode": "NY",
      "latitude": 40.71427,
      "longitude": -74.00597,
      "distance": 0
    },
    {
      "id": 106384,
      "wikiDataId": "Q11299",
      "city": "Manhattan",
      "country": "United States of America",
      "countryCode": "US",
      "region": "New York",
      "regionCode": "NY",
      "latitude": 40.78343,
      "longitude": -73.96625,
      "distance": 5.2
    },
    {
      "id": 106525,
      "wikiDataId": "Q18419",
      "city": "Brooklyn",
      "country": "United States of America",
      "countryCode": "US",
      "region": "New York",
      "regionCode": "NY",
      "latitude": 40.6501,
      "longitude": -73.94958,
      "distance": 5.3
    },
    {
      "id": 105752,
      "city": "Queens",
      "country": "United States of America",
      "countryCode": "US",
      "region": "New York",
      "regionCode": "NY",
      "latitude": 40.68149,
      "longitude": -73.83652,
      "distance": 9.2
    }
  ],
  "metadata": {
    "currentOffset": 0,
    "totalCount": 4
  }
}

Let's update the SPARQL query

From the above results, we now get the list of WikiData ids. Note that as of this writing, the WikiData id for Queens is missing. This is because GeoDB relies on the WikiData GeoNames property to correlate GeoNames data to WikiData, and the Queens entry is currently missing that property. Such situations should become less frequent over time as WikiData matures.

In the meantime though, we have the following list of WikiData ids:

• Q60 (NYC)
• Q11299 (Manhattan)
• Q18419 (Brooklyn)

The updated query uses the UNION operator to effectively OR together the triplets for these three cities, as follows:

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX wd: <http://www.wikidata.org/entity/>
PREFIX wdt: <http://www.wikidata.org/prop/direct/>

SELECT DISTINCT ?attraction ?attractionLabel ?gps 

WHERE {
    ?attraction (wdt:P31/wdt:P279*) wd:Q570116;
        wdt:P625 ?gps;
        rdfs:label ?attractionLabel.
 
    {?attraction wdt:P131 wd:Q60}
    UNION
    {?attraction wdt:P131 wd:Q11299}
    UNION
    {?attraction wdt:P131 wd:Q18419}
            
    FILTER(LANG(?attractionLabel) = "en")
}

Using the WikiData Query UI, this gives us the following results:

NOTE: Castle Clinton shows up twice due to two slightly different coordinate locations associated with it. This highlights a case where your code may occasionally have to do some slight judgment calls to decide which version to take.

Great, but how do I do this programmatically?

GeoDB Integration

• Java
• Angular
• Other Options

WikiData Integration

• HTTP REST

  https://query.wikidata.org/sparql?format=json&query={SPARQL}

• Java
• JavaScript
• Python

For more information on how to integrate with WikiData, go here.

Well done getting this far!

This was a long tutorial, but we hope you can now see the power of combining the GeoDB Cities API with WikiData to create novel and compelling user experiences. Please let us know what you come up with!