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,394,025 places-us crosswalk-us
cn China 10,902,252 places-cn crosswalk-cn
jp Japan 7,179,378 places-jp crosswalk-jp
de Germany 4,884,796 places-de crosswalk-de
it Italy 4,318,631 places-it crosswalk-it
fr France 3,490,995 places-fr crosswalk-fr
es Spain 3,221,815 places-es crosswalk-es
gb United Kingdom 3,150,185 places-gb crosswalk-gb
br Brazil 3,099,445 places-br crosswalk-br
ca Canada 1,958,577 places-ca crosswalk-ca
au Australia 1,566,800 places-au crosswalk-au
kr South Korea 1,534,878 places-kr crosswalk-kr
pt Portugal 1,193,894 places-pt crosswalk-pt
tw Taiwan 1,128,925 places-tw crosswalk-tw
ch Switzerland 812,688 places-ch crosswalk-ch
no Norway 771,665 places-no crosswalk-no
ru Russia 741,543 places-ru crosswalk-ru
se Sweden 740,433 places-se crosswalk-se
at Austria 702,798 places-at crosswalk-at
mx Mexico 679,835 places-mx crosswalk-mx
dk Denmark 644,866 places-dk crosswalk-dk
za South Africa 548,439 places-za crosswalk-za
in India 537,004 places-in crosswalk-in
id Indonesia 484,994 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,031 places-th crosswalk-th
ph Philippines 231,015 places-ph crosswalk-ph
sg Singapore 227,071 places-sg crosswalk-sg
ar Argentina 226,221 places-ar crosswalk-ar
hk Hong Kong 225,350 places-hk crosswalk-hk
ie Ireland 214,098 places-ie crosswalk-ie
pl Poland 203,818 places-pl crosswalk-pl
tr Turkey 160,602 places-tr crosswalk-tr
nz New Zealand 160,498 places-nz crosswalk-nz
my Malaysia 156,137 places-my crosswalk-my
il Israel 142,079 places-il crosswalk-il
cl Chile 108,705 places-cl crosswalk-cl
co Colombia 81,505 places-co crosswalk-co
hu Hungary 73,885 places-hu crosswalk-hu
vn Vietnam 44,104 places-vn crosswalk-vn
hr Croatia 43,354 places-hr crosswalk-hr
cz Czech Republic 33,750 places-cz crosswalk-cz
pr Puerto Rico 28,160 places-pr crosswalk-pr
lu Luxembourg 27,430 places-lu crosswalk-lu
ve Venezuela 26,348 places-ve crosswalk-ve
pe Peru 24,501 places-pe crosswalk-pe
gr Greece 24,391 places-gr crosswalk-gr
eg Egypt 11,994 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.