Working With Factual Global Places

Factual’s Global Places database has 65+ million entities in 50 countries, all accessible through our unified Global Places API.

Explore the data through our interactive data preview.

Schema

The schema for the global place data can be found here, or you can access it programmatically. You can find the complete list of categories used in our global place data here.

Supported Countries

The following countries are supported in Factual’s place data. As noted, diffs are currently available for specified tables. We’re working to make diffs available for all countries ASAP.

ISO Country code ▾ Country Rows1 Direct API endpoint2 Real-time Writes?3 Notes
All Countries 65+ million /t/places All countries in a single table
us United States 17,086,868 /t/places-us Y
cn China 17,283,145 /t/places-cn Y
de Germany 2,645,972 /t/places-de Y
fr France 3,775,548 /t/places-fr Y
jp Japan 6,170,899 /t/places-jp Y
gb United Kingdom 2,299,895 /t/places-gb Y
it Italy 2,432,586 /t/places-it Y
ca Canada 1,866,655 /t/places-ca Y
br Brazil 1,824,932 /t/places-br Y
es Spain 2,266,601 /t/places-es Y
au Australia 1,334,203 /t/places-au Y
se Sweden 868,212 /t/places-se Y
tw Taiwan 1,183,728 /t/places-tw Y
mx Mexico 696,277 /t/places-mx Y
ch Switzerland 680,596
ru Russia 667,809 /t/places-ru Y
at Austria 614,190 /t/places-at Y
dk Denmark 512,864
pt Portugal 666,655 /t/places-pt Y
no Norway 403,348
kr South Korea 407,637 /t/places-kr Y
fi Finland 376,277
nl Netherlands 351,572
be Belgium 257,703
ar Argentina 229,337
ie Ireland 229,029
sg Singapore 223,702 /t/places-sg Y
pl Poland 206,039
tr Turkey 123,314 /t/places-tr Y
hk Hong Kong 203,647 /t/places-hk Y
my Malaysia 156,719
in India 340,488 /t/places-in Y
id Indonesia 381,628 /t/places-id Y
cl Chile 110,113
th Thailand 127,266 /t/places-th Y
ph Philippines 94,300 /t/places-ph Y
nz New Zealand 100,198 /t/places-nz Y
co Colombia 82,077
hu Hungary 74,885
il Israel 142,190 /t/places-il Y
za South Africa 409,269
vn Vietnam 44,272
hr Croatia 43,745
cz Czech Republic 33,684
pr Puerto Rico 29,143
lu Luxembourg 28,536
ve Venezuela 28,420
pe Peru 24,450
gr Greece 24,384
eg Egypt 12,113

1 Row counts per country as of Jul 15, 2014 and use the default existence threshold.
2 Use this endpoint for any diffs API calls, or to avoid the performance penalty of determining what country the data you are searching for is in if you already know it.
3 Diffs API access is only available to developers with download licenses. Contact Factual for licensing information.

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 Starbucks near me (within 5 km of on my lat/lng):
http://api.v3.factual.com/t/places-us?q=starbucks&geo={"$circle":{"$center":[34.06021,-118.41828],"$meters":5000}}
Find a Starbucks in Santa Monica, CA, USA
http://api.v3.factual.com/t/places-us?q=starbucks&filters={"$and":[{"locality":"santa monica"},{"region":"ca"}]}
Find an Italian Restaurant near me
http://api.v3.factual.com/t/places-us?filters={"category_ids":{"$includes":358}}&geo={"$circle":{"$center":[34.06021,-118.41828],"$meters":5000}}

There is a comprehensive list of categories, and their associated Ids.

Find a Restauraunt or Bar in Santa Monica
http://api.v3.factual.com/t/places-us?filters={"$and":[{"category_ids":{"$includes_any":[312,347]}},{"locality":"santa monica"},{"region":"ca"}]}

Note that including a mid-level category like “Social > Food and Dining > Restaurants” (347) will implicitly include all nested categories (348-368).

Make your queries efficient

You’ll find that your queries will return significantly faster if you either:

  • Include a lat/lng in your query (using a geo filter)
  • Specify a country code in your query (using a row filter) or using the direct API endpoint for the country you are searching.
  • Provide enough detail that the place you are looking for can be uniquely identified. For example, filtering on a phone number or Factual Id.

Note: If you make too many inefficient queries in a short period, you may find your API calls periodically throttled.

Using the API to correct data.

Factual has a robust set of Write APIs for contributing new businesses, updating existing businesses and flagging data problems. There are many examples in the Write API documentation.