Working With Factual Global Places

Factual’s Global Places database has 70+ 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.

ISO Country code ▾ Country Rows1 Read API endpoint2 Crosswalk API endpoint Notes
All Countries 70+ million places All countries in a single table2
us United States 20,321,172 places-us crosswalk-us
cn China 10,902,245 places-cn crosswalk-cn
jp Japan 7,179,365 places-jp crosswalk-jp
de Germany 4,885,066 places-de crosswalk-de
it Italy 4,318,639 places-it crosswalk-it
fr France 3,490,797 places-fr crosswalk-fr
es Spain 3,221,814 places-es crosswalk-es
gb United Kingdom 3,150,285 places-gb crosswalk-gb
br Brazil 3,099,472 places-br crosswalk-br
ca Canada 1,958,627 places-ca crosswalk-ca
au Australia 1,566,792 places-au crosswalk-au
kr South Korea 1,534,876 places-kr crosswalk-kr
pt Portugal 1,193,896 places-pt crosswalk-pt
tw Taiwan 1,128,918 places-tw crosswalk-tw
ch Switzerland 812,693 places-ch crosswalk-ch
no Norway 771,667 places-no crosswalk-no
ru Russia 741,517 places-ru crosswalk-ru
se Sweden 937,439 places-se crosswalk-se
at Austria 702,796 places-at crosswalk-at
mx Mexico 601,360 places-mx crosswalk-mx
dk Denmark 644,866 places-dk crosswalk-dk
za South Africa 548,441 places-za crosswalk-za
in India 537,013 places-in crosswalk-in
id Indonesia 678,996 places-id crosswalk-id
fi Finland 364,974 places-fi crosswalk-fi
nl Netherlands 328,651 places-nl crosswalk-nl
be Belgium 256,942 places-be crosswalk-be
th Thailand 251,036 places-th crosswalk-th
ph Philippines 231,014 places-ph crosswalk-ph
sg Singapore 227,071 places-sg crosswalk-sg
ar Argentina 226,222 places-ar crosswalk-ar
hk Hong Kong 225,340 places-hk crosswalk-hk
ie Ireland 302,380 places-ie crosswalk-ie
pl Poland 203,818 places-pl crosswalk-pl
tr Turkey 160,606 places-tr crosswalk-tr
nz New Zealand 160,500 places-nz crosswalk-nz
my Malaysia 462,899 places-my crosswalk-my
il Israel 171,833 places-il crosswalk-il
cl Chile 108,705 places-cl crosswalk-cl
co Colombia 135,046 places-co crosswalk-co
hu Hungary 95,051 places-hu crosswalk-hu
vn Vietnam 161,499 places-vn crosswalk-vn
hr Croatia 114,396 places-hr crosswalk-hr
cz Czech Republic 169,693 places-cz crosswalk-cz
pr Puerto Rico 48,013 places-pr crosswalk-pr
lu Luxembourg 41,784 places-lu crosswalk-lu
ve Venezuela 62,305 places-ve crosswalk-ve
pe Peru 126,453 places-pe crosswalk-pe
gr Greece 78,596 places-gr crosswalk-gr
eg Egypt 208,342 places-eg crosswalk-eg

1 Row counts reflect Jun 3, 2015 data using the default existence threshold.

2 Always use the direct endpoint (e.g., places-us) if you know the country you are searching against, if available. The direct endpoints are much higher performance. Countries without a direct endpoint shown must be accessed by the global endpoint (places).

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 country-specific read 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.