Introduction

Schema

The schema for the global place data can be found here, or you can access it programmatically:

Syntax and Examples

You can query global places with a single, simple (but powerful) API call.  Note that all of the examples are shown below without URL encoding for clarity.  In practice, you'll need to encode each example when making requests.

Find a place by its name

For example, let's try to find any Starbucks in the world: (run this query)

If things go properly, you'll get a whole bunch of results like this:

Filter places by city

OK...  So you got your list of Starbucks, but it's a bit too noisy for your user who's sitting in Los Angeles.  Let's restrict your search to Starbucks in Los Angeles (using the "equals" row filter): (run this query)

Filter places by multiple cities

Santa Monica and Los Angeles border each other.  Maybe we want Starbucks in either city?  We can use the in operator for that: (run this query)

Filter places by category

Aha!  But maybe instead of just Starbucks, they'd like to find any places categorized as Food & Beverage > Cafes, Coffee Houses & Tea Houses in Los Angeles or Santa Monica: (run this query)

Avoid this common mistake! A number of Factual categories contain the & symbol, which trips up some URL Encoders. The easiest solution is to replace the ampersands with their encoded equivalent (%26) before you encode the rest of your request. For example, for the category above, use: Food %26 Beverage > Cafes, Coffee Houses %26 Tea Houses

Find places near your address

That works.  But what if my user wants something even more personal?  Maybe they are visiting Factual, and they want to find a bar near the Factual office:

1. First, get the latitude and longitude of the Factual Office using the one of our favorite tools, the Data Science Toolkit: (run this query)

2. Take the lat/lng you received (34.061157, -118.418277) and generate a geo query for bars within 1000 meters of Factual: (run this query)

Filter places by a top-level category

Oops- I see a hair salon in there:

Maybe I only want things categorized under Arts, Entertainment & Nightlife: (run this query)

Voila!  Hopefully you've learned enough to get started using the Factual API to build something with our global database.

Limitations

There are currently a number of known limitations that we're working to resolve:

• Outside of the United States, the search API does not contain automatic lookups for a number of region codes to names. For example, to find data in British Columbia, you need to make sure you search region for the two letter abbreviation BC.
• The API also does not contain lookups for two letter country codes to either their fully spelled out English or their internationalized names.
• The API also does no contain English synonyms for international locality or region names. For example, to find places in Tokyo, you will need to search locality for 東京都. This is in keeping with the spirit of the data being presented in language appropriate to the data.

Help and further resources

If you need further help, here are some links:

• How to write Factual Queries
• Global Places Schema
• Using Apigee
• Factual Core API
• Factual Places API (cool stuff like Resolve and Crosswalk!)
• Factual Read API Filters: Geo - Row - Full-text-search
• Java and Clojure drivers for accessing Factual data
• Factual Developer Group

* Apigee has a bug relating to URL's with the '%' char in them. To see these responses neatly formatted in your browser, try JSONView for Chrome or Firefox.