Menu

GeoDB Cities API - Find Cities For Your Criteria | Wirefree Thought

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:

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:

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.mashape.com/v1/geo/cities?namePrefix=New&minPopulation=1000000' \
    -H 'X-Mashape-Key: YOUR_API_KEY' \
    -H 'X-Mashape-Host: wft-geo-db.p.mashape.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:

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:

attraction attractionLabel gps
http://www.wikidata.org/entity/Q6940939National Museum of MathematicsPoint(-73.9883 40.7437)
http://www.wikidata.org/entity/Q952270Intrepid Sea, Air & Space MuseumPoint(-74.00083333 40.76472222)
http://www.wikidata.org/entity/Q18343137Godwin-Ternbach MuseumPoint(-73.817274 40.73634)
http://www.wikidata.org/entity/Q179847489/11 Tribute MuseumPoint(-74.012416666 40.710083333)
http://www.wikidata.org/entity/Q29469136Choco-Story New YorkPoint(-74.00683 40.727664)
http://www.wikidata.org/entity/Q18157051Pulitzer FountainPoint(-73.9736 40.764)

That's it? Why so few results?

WikiData entities tend to refer to very specific things. When you directly ask it 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.mashape.com/v1/geo/cities/Q60/nearbyCities?radius=10&minPopulation=500000' \
    -H 'X-Mashape-Key: YOUR_API_KEY' \
    -H 'X-Mashape-Host: wft-geo-db.p.mashape.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:

attraction attractionLabel gps
http://www.wikidata.org/entity/Q1278593Museum of Chinese in AmericaPoint(-73.999444444 40.716111111)
http://www.wikidata.org/entity/Q1136137National September 11 Memorial & MuseumPoint(-74.013611111 40.711388888)
http://www.wikidata.org/entity/Q1129820Cooper Hewitt, Smithsonian Design MuseumPoint(-73.95805556 40.78472222)
http://www.wikidata.org/entity/Q1139071New York City Police MuseumPoint(-74.008192 40.703538)
http://www.wikidata.org/entity/Q1059456New-York Historical SocietyPoint(-73.974166666 40.779166666)
http://www.wikidata.org/entity/Q808531Barnum's American MuseumPoint(-74.0086 40.7112)
http://www.wikidata.org/entity/Q839985Museum of Jewish HeritagePoint(-74.01875 40.70621)
http://www.wikidata.org/entity/Q901533Lower East Side Tenement MuseumPoint(-73.990139 40.7185)
http://www.wikidata.org/entity/Q1478423The Morgan Library & MuseumPoint(-73.981556 40.748803)
http://www.wikidata.org/entity/Q1503777New York Transit MuseumPoint(-73.99 40.6904)
http://www.wikidata.org/entity/Q2915494Skyscraper MuseumPoint(-74.0175 40.705555555)
http://www.wikidata.org/entity/Q632682Brooklyn MuseumPoint(-73.96375 40.671306)
http://www.wikidata.org/entity/Q63751Rubin Museum of ArtPoint(-73.997805555 40.740111111)
http://www.wikidata.org/entity/Q124302Chelsea Art MuseumPoint(-74.007 40.74783333)
http://www.wikidata.org/entity/Q59468Neue GaleriePoint(-73.9603 40.7813)
http://www.wikidata.org/entity/Q160236Metropolitan Museum of ArtPoint(-73.96367 40.77891)
http://www.wikidata.org/entity/Q2420849Hispanic Society of AmericaPoint(-73.9465 40.8335)
http://www.wikidata.org/entity/Q201469Solomon R. Guggenheim MuseumPoint(-73.958889 40.783056)
http://www.wikidata.org/entity/Q188740Museum of Modern ArtPoint(-73.977664 40.761484)
http://www.wikidata.org/entity/Q639791Whitney Museum of American ArtPoint(-74.0089 40.7396)
http://www.wikidata.org/entity/Q636942International Center of PhotographyPoint(-73.9834 40.7558)
http://www.wikidata.org/entity/Q682827The Frick CollectionPoint(-73.9675 40.771111111)
http://www.wikidata.org/entity/Q592116Jewish MuseumPoint(-73.9575 40.7854)
http://www.wikidata.org/entity/Q1061142El Museo del BarrioPoint(-73.9514 40.7931)
http://www.wikidata.org/entity/Q903403Studio Museum HarlemPoint(-73.947533333 40.808477777)
http://www.wikidata.org/entity/Q1138030The CloistersPoint(-73.931905 40.86484)
http://www.wikidata.org/entity/Q1321141Museum of the City of New YorkPoint(-73.951944444 40.7925)
http://www.wikidata.org/entity/Q1156823New MuseumPoint(-73.992916666 40.722361111)
http://www.wikidata.org/entity/Q464354American Folk Art MuseumPoint(-73.9781 40.7616)
http://www.wikidata.org/entity/Q3328431Museum of Comic and Cartoon ArtPoint(-73.9871 40.7401)
http://www.wikidata.org/entity/Q3039170Drawing CenterPoint(-74.0029 40.7224)
http://www.wikidata.org/entity/Q2999991Dahesh Museum of ArtPoint(-74.00480556 40.725)
http://www.wikidata.org/entity/Q1954603The Africa CenterPoint(-73.928333333 40.746388888)
http://www.wikidata.org/entity/Q3021342Deitch ProjectsPoint(-74.0025 40.722)
http://www.wikidata.org/entity/Q5362267Elizabeth A. Sackler Center for Feminist ArtPoint(-73.9638 40.6713)
http://www.wikidata.org/entity/Q5159606Coney Island USAPoint(-73.9798 40.5753)
http://www.wikidata.org/entity/Q6052565International Print Center New YorkPoint(-74.0043 40.7501)
http://www.wikidata.org/entity/Q4884230Bellwether GalleryPoint(-74.0062 40.7449)
http://www.wikidata.org/entity/Q5098177Children's Museum of ManhattanPoint(-73.9772 40.7859)
http://www.wikidata.org/entity/Q4470591Ukrainian MuseumPoint(-73.9897 40.7278)
http://www.wikidata.org/entity/Q5422747Eyebeam Art and Technology CenterPoint(-74.00712222 40.74710556)
http://www.wikidata.org/entity/Q5354207Museum of American FinancePoint(-74.0092 40.7064)
http://www.wikidata.org/entity/Q6516654Lefferts Historic HousePoint(-73.9638 40.6643)
http://www.wikidata.org/entity/Q7703226Terrain GalleryPoint(-73.9988 40.726)
http://www.wikidata.org/entity/Q7338883Rivington ArmsPoint(-73.9836 40.7187)
http://www.wikidata.org/entity/Q6530976Leslie Lohman Museum of Gay and Lesbian ArtPoint(-74.0031 40.7216)
http://www.wikidata.org/entity/Q6940773Museum of Arts and DesignPoint(-73.9819 40.7675)
http://www.wikidata.org/entity/Q6940781Museum of Biblical ArtPoint(-73.9827 40.7702)
http://www.wikidata.org/entity/Q5539979National Museum of the American Indian George Gustav Heye CenterPoint(-74.0138 40.7043)
http://www.wikidata.org/entity/Q6659326Living Torah MuseumPoint(-73.9808 40.6356)
http://www.wikidata.org/entity/Q7085115Old Stone HousePoint(-73.984625 40.672958)
http://www.wikidata.org/entity/Q6924383Mount Vernon Hotel MuseumPoint(-73.96 40.760556)
http://www.wikidata.org/entity/Q8052851Yeshiva University MuseumPoint(-73.9939 40.7381)
http://www.wikidata.org/entity/Q7579760Sports Museum of AmericaPoint(-74.0132 40.7051)
http://www.wikidata.org/entity/Q572548Anthology Film ArchivesPoint(-73.9901 40.7247)
http://www.wikidata.org/entity/Q952270Intrepid Sea, Air & Space MuseumPoint(-74.00083333 40.76472222)
http://www.wikidata.org/entity/Q6941063Museum of the American GangsterPoint(-73.9858 40.7279)
http://www.wikidata.org/entity/Q6940955Museum of MotherhoodPoint(-73.9499 40.7756)
http://www.wikidata.org/entity/Q7026138Nicholas Roerich MuseumPoint(-73.9691 40.8029)
http://www.wikidata.org/entity/Q6973870National Jazz Museum in HarlemPoint(-73.938 40.8055)
http://www.wikidata.org/entity/Q6940939National Museum of MathematicsPoint(-73.9883 40.7437)
http://www.wikidata.org/entity/Q7979549Weeksville Heritage CenterPoint(-73.9254 40.674)
http://www.wikidata.org/entity/Q18343137Godwin-Ternbach MuseumPoint(-73.817274 40.73634)
http://www.wikidata.org/entity/Q2865930Dyckman HousePoint(-73.923056 40.867361)
http://www.wikidata.org/entity/Q3306353Merchant's House MuseumPoint(-73.992361111 40.727666666)
http://www.wikidata.org/entity/Q3784918Henry Clay Frick HousePoint(-73.9672 40.7711)
http://www.wikidata.org/entity/Q217717American Museum of Natural HistoryPoint(-73.974722222 40.780555555)
http://www.wikidata.org/entity/Q29469136Choco-Story New YorkPoint(-74.00683 40.727664)
http://www.wikidata.org/entity/Q16025238South Street Seaport MuseumPoint(-74.0028 40.7061)
http://www.wikidata.org/entity/Q7768627The Theatre MuseumPoint(-73.9839 40.7599)
http://www.wikidata.org/entity/Q1087567National Track and Field Hall of FamePoint(-73.94125 40.84213889)
http://www.wikidata.org/entity/Q179847489/11 Tribute MuseumPoint(-74.012416666 40.710083333)
http://www.wikidata.org/entity/Q18748945Brooklyn Museum Libraries and ArchivesPoint(-73.9636306 40.6712062)
http://www.wikidata.org/entity/Q18154623Morbid Anatomy MuseumPoint(-73.9901 40.6728)
http://www.wikidata.org/entity/Q954207Central Park ZooPoint(-73.971666666 40.767777777)
http://www.wikidata.org/entity/Q7927217Victorian GardensPoint(-73.9773 40.7686)
http://www.wikidata.org/entity/Q1058899Prospect Park ZooPoint(-73.964361111 40.665772222)
http://www.wikidata.org/entity/Q5092377Cherry HillPoint(-73.9727 40.7747)
http://www.wikidata.org/entity/Q4848351Bailey FountainPoint(-73.9649 40.6655)
http://www.wikidata.org/entity/Q532029Bethesda TerracePoint(-73.9711 40.7741)
http://www.wikidata.org/entity/Q17151590Untermyer FountainPoint(-73.95195 40.79426)
http://www.wikidata.org/entity/Q18157051Pulitzer FountainPoint(-73.9736 40.764)
http://www.wikidata.org/entity/Q665475Hayden PlanetariumPoint(-73.9732 40.7815)
http://www.wikidata.org/entity/Q5359415Elephantine ColossusPoint(-73.9783 40.5767)
http://www.wikidata.org/entity/Q1322466Museum of SexPoint(-73.987 40.7443)
http://www.wikidata.org/entity/Q1060884New York AquariumPoint(-73.9751 40.5743)
http://www.wikidata.org/entity/Q4974780Brooklyn Children's MuseumPoint(-73.9439 40.6745)
http://www.wikidata.org/entity/Q1049423Castle ClintonPoint(-74.01681 40.70348)
http://www.wikidata.org/entity/Q1049423Castle ClintonPoint(-74.016667 40.703611)

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

WikiData Integration

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!