Working With Factual Global Places

Factual’s Global Places database has 84+ 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 84+ million places All countries in a single table2
us United States 19,150,386 places-us crosswalk-us
cn China 11,248,677 places-cn crosswalk-cn
jp Japan 7,105,571 places-jp crosswalk-jp
de Germany 5,511,911 places-de crosswalk-de
it Italy 4,121,802 places-it crosswalk-it
fr France 4,234,822 places-fr crosswalk-fr
es Spain 2,778,641 places-es crosswalk-es
gb United Kingdom 3,038,984 places-gb crosswalk-gb
br Brazil 3,311,830 places-br crosswalk-br
ca Canada 1,870,390 places-ca crosswalk-ca
au Australia 1,583,844 places-au crosswalk-au
kr South Korea 2,188,018 places-kr crosswalk-kr
pt Portugal 1,260,050 places-pt crosswalk-pt
tw Taiwan 701,652 places-tw crosswalk-tw
ch Switzerland 839,434 places-ch crosswalk-ch
no Norway 707,387 places-no crosswalk-no
ru Russia 719,998 places-ru crosswalk-ru
se Sweden 812,072 places-se crosswalk-se
at Austria 705,296 places-at crosswalk-at
mx Mexico 1,008,882 places-mx crosswalk-mx
dk Denmark 494,644 places-dk crosswalk-dk
za South Africa 519,719 places-za crosswalk-za
in India 447,013 places-in crosswalk-in
id Indonesia 874,893 places-id crosswalk-id
fi Finland 376,798 places-fi crosswalk-fi
nl Netherlands 1,330,598 places-nl crosswalk-nl
be Belgium 431,895 places-be crosswalk-be
th Thailand 284,550 places-th crosswalk-th
ph Philippines 397,599 places-ph crosswalk-ph
sg Singapore 341,656 places-sg crosswalk-sg
ar Argentina 313,822 places-ar crosswalk-ar
hk Hong Kong 206,078 places-hk crosswalk-hk
ie Ireland 313,417 places-ie crosswalk-ie
pl Poland 1,477,963 places-pl crosswalk-pl
tr Turkey 612,567 places-tr crosswalk-tr
nz New Zealand 198,817 places-nz crosswalk-nz
my Malaysia 594,742 places-my crosswalk-my
il Israel 131,470 places-il crosswalk-il
cl Chile 212,625 places-cl crosswalk-cl
co Colombia 412,715 places-co crosswalk-co
hu Hungary 163,715 places-hu crosswalk-hu
vn Vietnam 150,485 places-vn crosswalk-vn
hr Croatia 132,497 places-hr crosswalk-hr
cz Czech Republic 222,966 places-cz crosswalk-cz
pr Puerto Rico 71,237 places-pr crosswalk-pr
lu Luxembourg 48,140 places-lu crosswalk-lu
ve Venezuela 32,354 places-ve crosswalk-ve
pe Peru 109,827 places-pe crosswalk-pe
gr Greece 133,583 places-gr crosswalk-gr
eg Egypt 220,144 places-eg crosswalk-eg

1 Row counts reflect Dec 16, 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.