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.

ISO Country code ▾ Country Rows1 Read API endpoint2 Crosswalk API endpoint Real-time Writes?3 Notes
All Countries 65+ million places All countries in a single table2
us United States 17,552,840 /t/places-us /t/crosswalk-us Y
cn China 10,175,901 /t/places-cn /t/crosswalk-cn Y
jp Japan 7,264,061 /t/places-jp /t/crosswalk-jp Y
it Italy 4,524,340 /t/places-it /t/crosswalk-it Y
de Germany 3,355,941 /t/places-de /t/crosswalk-de Y
fr France 3,252,012 /t/places-fr /t/crosswalk-fr Y
es Spain 3,166,471 /t/places-es /t/crosswalk-es Y
gb United Kingdom 3,132,359 /t/places-gb /t/crosswalk-gb Y
br Brazil 3,015,173 /t/places-br /t/crosswalk-br Y
ca Canada 2,136,945 /t/places-ca /t/crosswalk-ca Y
au Australia 1,496,498 /t/places-au /t/crosswalk-au Y
kr South Korea 1,218,022 /t/places-kr /t/crosswalk-kr Y
tw Taiwan 1,151,200 /t/places-tw /t/crosswalk-tw Y
pt Portugal 982,940 /t/places-pt /t/crosswalk-pt Y
ru Russia 751,159 /t/places-ru /t/crosswalk-ru Y
se Sweden 740,427 /t/places-se /t/crosswalk-se Y
at Austria 679,631 /t/places-at /t/crosswalk-at Y
mx Mexico 675,399 /t/places-mx /t/crosswalk-mx Y
ch Switzerland 674,167
dk Denmark 656,159 /t/places-dk /t/places-dk Y
no Norway 492,239 /t/places-no /t/places-no Y
id Indonesia 464,869 /t/places-id /t/crosswalk-id Y
in India 456,713 /t/places-in /t/places-in Y
fi Finland 376,251
za South Africa 307,432 /t/places-za /t/crosswalk-za Y
be Belgium 257,378
sg Singapore 236,533 /t/places-sg /t/crosswalk-sg Y
ie Ireland 229,009
th Thailand 227,413 /t/places-th /t/crosswalk-th Y
ar Argentina 222,162 /t/places-ar /t/places-ar Y
hk Hong Kong 212,484 /t/places-hk /t/crosswalk-hk Y
nz New Zealand 210,170 /t/places-nz /t/crosswalk-nz Y
pl Poland 206,030
tr Turkey 182,298 /t/places-tr /t/places-tr Y
my Malaysia 156,694
il Israel 142,060 /t/places-il Y
ph Philippines 131,131 /t/places-ph /t/crosswalk-ph Y
co Colombia 81,186
hu Hungary 73,605
vn Vietnam 44,272
hr Croatia 43,428
cz Czech Republic 33,142
pr Puerto Rico 29,138
ve Venezuela 28,417
lu Luxembourg 27,915
cl Chile 27,815
pe Peru 24,139
gr Greece 23,979
eg Egypt 12,111
nl Netherlands 3,511

1 Row counts reflect Mar 23, 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).

3 For any country that supports real-time writes, you must use the direct endpoint (e.g., places-us) and not 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.