Factual Android SDK

Factual would like to announce the release of the new, officially supported SDK for Android!  Some of you may already be using the Factual Java driver in your Android project, so what’s so different about this version?  We’ve done several things for you:

  1. Defined the exact dependencies needed to get up and running on an Android device.
  2. Provided a sample Android project.  Copy this project as a model for incorporating Factual data in your own application, or use it as a starter to immediately begin work on your new application.


If you’re using Maven, add the driver to your project using:


Otherwise, check the pom.xml file for the required dependencies.

Once you have the driver installed in your Java project, here’s how you create an authenticated handle to Factual:

Factual factual = new Factual("YOUR_API_KEY", "YOUR_API_SECRET");

Next, simply create the request of your choice, and fetch the results.


Consider searching for Italian restaurants nearby your current location.  Use the Android location service to get your current phone location:

LocationManager locationManager =
  (LocationManager) getSystemService(Context.LOCATION_SERVICE);
String locationProvider = LocationManager.GPS_PROVIDER;
Location location = locationManager.getLastKnownLocation(locationProvider);
double latitude = location.getLatitude();
double longitude = location.getLongitude();

Now create a query to find Italian restaurants within 1000 meters of your current location, sorted by distance:

Query query = new Query()
.within(new Circle(latitude, longitude, 1000))

Fetch and print the results against the Restaurants data set:

ReadResponse italian = factual.fetch("restaurants-us", query);
for (Map restaurant : italian.getData()) {
    String name = (String) restaurant.get("name");
    String address = (String) restaurant.get("address");
    String phone = (String) restaurant.get("tel");
    Number distance = (Number) restaurant.get("$distance");
    System.out.println(distance + " meters away: "+name+" @ " +address + ", call "+phone);

Sample results searching near our Factual office are:

186.77191 meters away: Obika Mozzarella Bar - Century City @ 10250 Santa Monica Blvd, call (310) 556-2452
186.77191 meters away: Toscanova @ 10250 Santa Monica Blvd, call (310) 551-0499
813.8221 meters away: Carmine's II @ 10463 Santa Monica Blvd, call (310) 441-4706

Great!  There are several options nearby.  Now let’s say we want our application to be able to call and make a reservation at Toscanova.  We already have the phone number, so just use the Android APIs to access the phone on the device to make the call:

String uri = "tel:" + phone;
Intent intent = new Intent(Intent.ACTION_CALL);

As another example, let’s say you’re on the road, and it’s late.  You’re set to arrive at your hotel at 2 am, and you’ll be hungry.  Use Factual to find restaurants open 24 hours near the location of your hotel.  First, retrieve the latitude and longitude of the hotel using our Places dataset.  Our Restaurants schema, has an attribute “open_24hrs”, so your query is as follows:

new Query()
.within(new Circle(latitude, longitude, meters))

Looking through the results, you find the place you’re looking for:

1769.1987 meters away: IHOP @ 1850 Soldiers Field Rd, call (617) 787-0533


The above examples show how developing on a mobile device is a great way to take full advantage of the data Factual has to offer, opening up new possibilities for creating lots of cool applications.  All APIs available in the Java driver are available in the Android SDK, and complete documentation can be found on the driver’s Github page.

We hope you find these updates useful, and feel free to let us know if you end up using the driver for any new Android applications, as we’re always excited to see ways that people are using our data.  Let us know if you have any questions or suggestions, and we hope you’ll enjoy using Factual in your mobile applications!

New to Factual?  Explore our data offerings, learn about our APIs, and sign up to get started!

Best wishes,
Brandon Yoshimoto
Software Engineer

Launching Location and Mobile Ad Targeting Tools

To enhance our Global Places offering, we are announcing three new APIs that will provide developers with powerful geointelligence tools and data designed to increase contextual relevance in today’s mobile world:

Geopulse API

Discover everything that Factual knows about a location: you pass us a latitude and longitude, and we return additional attributes, called ‘pulses’, about that location.  Pulses employ Factual’s network of signals, calculated metrics, and census data to give a unique purview of a given local point.  We’re launching with:

  • Factual Commercial Density: Relative density of businesses near a location
  • Factual Commercial Profile: Types of businesses near a location
  • Demographics: Age, gender, race, median household income for a given location (US only)

We’ll be adding more over the coming months.  Have a look at the demo and documentation to learn more.  Pricing will depend on use case and usage volume.

Reverse Geocoder API

Convert a longitude and latitude into an address for the US and 49 other countries.  More details.

World Geographies API

Learn the names and interrelationships between the world’s natural and administrative geographies — countries, cities, states, continents, regions, and time zones — enhancing the global 60 million businesses and landmarks we currently offer. You will be able to access ~6 million geographies and over 8 million place names in numerous languages.  More details.

With data accessible via these additional APIs, it will make it even easier for developers and enterprises to build smarter location-based applications and analytics / business intelligence models. These services are production-ready but we’re launching them in beta, which means we will likely be making changes in the short-term as we incorporate developer feedback.

These new APIs are focused on addressing the mobile ad targeting market.  ThinkNear, a hyperlocal mobile demand side platform, is using Factual services to build a more robust ad targeting platform, and in the next few weeks we’ll be announcing more partnerships who are providing advertisers with advanced targeting and analytics using our location-centric toolkit.

This is really just the beginning — more services are coming , but we hope this gives you a sense of where we are headed and the means to take them for a spin and provide feedback.

Factual Endpoints

Lastly, as an added bonus, we’ve made all data for a Factual entity accessible from a single endpoint — add the Factual ID to the end of http://www.factual.com/ and we will provide the core attributes with extended, rich data from our Crosswalk, Restaurants, and Healthcare Providers products.   A few examples:

We’re looking forward to seeing the innovative applications in which our developer community employs these new services.  Don’t hesitate to hit us up with feedback and feature requests.

Bill Michels
VP of Product Management and Partnerships
(currently at 34.06, -118.42)

Factual Releases Drivers that Matter: Python, Clojure, Haskell

As Factual adds more data and features to its APIs, it’s important that developers have it easy. So we’ve put our heart into releasing client side drivers that matter. Yes, we’ve got drivers like the Java driver and the PHP driver and stuff like that, if that’s what you need. But we’ve also fielded a few drivers that matter in their own special ways:


Python is the greatest scripting language ever created. It does “everything-is-an-object” and gets it right, has a general feel of solid design, and is an unmitigated joy to hack with. Grab Factual’s Python driver (it’s in PyPI), authenticate, and get going:

from factual import Factual
factual = Factual(YOUR_KEY, YOUR_SECRET)
factual.table("places").search("sushi santa monica")

That gives you businesses in Santa Monica that match a full text search for “sushi”. Select one and use Factual’s Crosswalk to get more info from other respected web authorities:


BAM! Tasty data, check it out:

  "url": "http://www.allmenus.com/ca/los-angeles/69110-california-pizza-kitchen/info",
  "factual_id": "110ace9f-80a7-47d3-9170-e9317624ebd9",
  "namespace_id": "69110",
  "namespace": "allmenus"
  "url": "http://api.bitehunter.com/v2.0/restaurants/id/67e030af8d75b7d595bf5e86d6ad5126",
  "factual_id": "110ace9f-80a7-47d3-9170-e9317624ebd9",
  "namespace_id": "67e030af8d75b7d595bf5e86d6ad5126",
  "namespace": "bitehunter"
  "url": "http://www.facebook.com/pages/California-Pizza-Kitchen-Westwood-VillageUCLA/152206654808652",
  "factual_id": "110ace9f-80a7-47d3-9170-e9317624ebd9",
  "namespace_id": "152206654808652",
  "namespace": "facebook"

That Crosswalk stuff, BTW, is neat-o. See how Factual gives you links out to guys like Facebook and AllMenus? There’s also Crosswalk data for Yelp, Foursquare, and lots of others.


Clojure is a Lisp and Lisp is the most powerful programming language known to mankind. Virtually free reign with macros, closures, DSLs… it’s crazy.

If you want to use the world’s most powerful programming language to query the world’s most powerful open data platform, grab PrettyQL (available via Clojars) and make it happen:

(select restaurants-us
  (around {:lat 34.06021 :lon -118.4183 :miles 3})
  (search "cigar")
      (= :alcohol true)
      (= :meal_dinner true)
      (= :parking_free true)))

That pretty snippet of code searches for a cigar shop near me where I can have dinner and drinks and not pay for parking. Check out the spicy results, mate:

({:open_24hrs false,
  :status "1",
  :country "US",
  :longitude -118.408088,
  :factual_id "5e2c36e4-aeb8-49b8-8652-defcd8ad5808",
  :parking_free true,
  :payment_cashonly false,
  :name "Buena Vista Cigar Club",
  :postcode "90210",
  :locality "Beverly Hills",
  :alcohol true,
  :alcohol_bar true,
  :owner "Rigo Fernandez",
  :latitude 34.058085,
  :meal_dinner true,
  :meal_cater true,
  :parking true,
  :region "CA",
  :address "9715 Santa Monica Blvd",
  :website "http://www.buenavistacigarclub.com/",
  :tel "(310) 273-8100",
  :category "Shopping > Tobacco Shops",
  :$distance 969.9574})


Haskell is the king of purely-functional, lazy, statically-typed languages. Write some Haskell and know that “if your code compiles it runs correctly”. Enjoy the same level of confidence using Factual… just plug in the Factual Haskell driver (factual-api in Cabal), and away you go:

let token = generateToken yourKey yourSecret
let query = ResolveQuery [ ResolveStr "name" "McDonalds"
                         , ResolveStr "address" "10451 Santa Monica Blvd" ]

That runs Factual’s Resolve service on a few business attributes and gives you back a “resolved” Factual entity. Now you can have confidence in your code AND your data.

But wait there’s more!

This was a whirlwind tour of a few selected client side drivers for Factual. But this hardly touches the full set of Factual’s live data and APIs. And there’s more data on the way, and more features on top of that.

We’ve also published drivers for Java, Ruby, PHP and iOS, with .NET and Android on the way. Just in case you’re… you know… into that sort of thing.

Best wishes,
Aaron Crow
Software Engineer

Heads-Up: New Categories for Global Places On-Deck

This is a quick heads-up to Factual developers and data partners to note that we will shortly be making significant changes to how our Global Places are categorized.

The Reasoning:

Our current categorization is based entirely on strings and does not use IDs; this makes queries cumbersome, locks us into a single language, and ossifies the classification system. All require fixing. We also received a large number of comments from our developers and partners in the last year on where the classification system can be improved, and we want to implement these. Lastly, we’re laying the groundwork for our move towards multi-categorization and a polyhierarchical taxonomy.

The Changes:

  • Each category will have a numeric ID; labels for each category will be provided in multiple languages
  • The shape of the hierarchy has been modified, and new nodes added (a few have been removed; we’re keen to keep it lean). Some categories have been split for better granularity
  • All Global Places are being re-classified for accuracy, as will our associated US Restaurants and US Healthcare Provides tables
  • The hierarchy is available as a structured JSON file to permit greater intelligence & query pre-processing on the client side; we’ll also provide a mapping file between old-and-new categories
  • Category search in the API will include all subcategories by default
  • Category strings in English will remain available for all Global Places
  • We’ve added Landmarks & Transportation nodes, and our Social and Retail nodes have made significant improvement in accuracy and coverage

The Timing:

You’ll see this happen in May 2012. We’ll keep our old categories attached to a static copy of the data through October, so no code changes on your side will be required immediately. However, you’ll want to move over as soon as convenient to take advantage of the new categories and new Places. Above all else, our goal is to increase the power of classification while minimizing developer disturbance. We’ll provide more details here and on the developer list as we have them. In the interim, have a look at the new Factual taxonomy on Github.

-Tyler Bell
Categorically Factual

Announcing China Places

你 好! Welcome to China, the world’s fastest-growing major economy, with annual growth rates averaging 10% over the past 30 years. This incredible growth has led China to become the world’s largest exporter and second largest importer of goods. If you have ever thought about tapping into this behemoth of a country, you may be interested with the latest country to leave beta.

Factual’s Shanghai team is excited to announce the formal release of China Places, covering the mainland region of People’s Republic of China. It is currently the second largest country dataset in Factual’s Global Places with over 9.5 million records, including 800K in Shanghai, 600K in Beijing and 250K entities in Guangzhou. The category makeup is around 43% Business & Professional Services, 11% Shopping and 9% Food & Beverage.

If you are developing apps that require China places, points of interest, and landmarks, data is now available through our Global API.

Learn More:

Allen Zheng
Factual Data Engineer, Shanghai



Hi! 欢迎来到中国。随着30年以来近10%的年经济增长,中国已经成为世界上发展最快的经济体。惊人的发展速度使得中国成为世界上最大的出口国和第二大的货物贸易进口国。如果你曾经想了解中国这个“庞然大物”,那么现在你也许会对我们新发布的中国地点数据感兴趣。

Factual上海团队很高兴地向大家宣布今天我们发布了中国地点数据的正式版。新版本的中国地点数据总共拥有大约950万条记录,覆盖了整个中国大陆地区,是目前Factual全球地点数据库中第二大的国家数据集。其中上海地区拥有约80万条数据记录,北京地区约有60万条记录,广州约有20万条记录。这些数据涵盖了商务公司(43%), 购物消费(11%),餐饮住宿(9%)等主要分类。

如果你正在开发与中国兴趣地点相关的应用,你现在可以通过我们的Global API来使用这些数据。


Allen Zheng