We put a priority on making this driver easy to use. It lets you focus on building your Factual queries and using the results in Java. It handles details like OAuth, url encoding, and JSON marshaling so you don’t have to.
The driver is hosted on Maven Central, so if you’re using Maven you can install it in your project just by adding this to your pom file:
Once you have the driver installed in your Java project, here’s how you create an authenticated handle to Factual:
The driver provides a fluent interface to build your Factual queries. For example, here’s how you build a query to use full text search and a geo filter to find cafes within 5,000 meters of your location, using your latitude and longitude:
There’s also fluent support for detailed results filtering. To illustrate a bit of this, here’s how you build a query to return the name and address of cafes within 5,000 meters of a lat/long, while limiting to a specific zip code, category, and size of returned results:
We’re also experimenting with built-in support for the venerable Data Science Toolkit. This gives you an easy way to lookup location coordinates based on address information. For example, you could find Factual’s latitude and longitude by using the text “1801 avenue of the stars, century city, ca”:
This support is built in to the driver’s fluid interface for querying on Factual’s Places data. Here’s an example of finding cigar shops within 5,000 meters of an address:
Crosswalk The Web
The driver has full support for Crosswalk, which makes it super easy for you to translate how Place entities are represented by 3rd party APIs and websites.
To illustrate, let’s take a look at the first record returned from our cigar search:
Each record represents a specific Crosswalk authority, or what we call a “namespace”, e.g. “yelp”, “facebook”, “yellowpages”, and so on.
Attributes include the namespace’s link and ID for the entity. E.g., the Yelp link for the Buena Vista Cigar Club is http://www.yelp.com/biz/buena-vista-cigar-club-beverly-hills, and the Yelp ID is “u_3ywlxdwq–WxxOO_3TVg”.
Crosswalk lets you go the other direction as well. Say all you have is the Facebook ID for the Buena Vista Cigar Club. You can do this…
… which includes the Factual ID of the entity. With that you can continue querying Factual’s system for whatever you want to know about the entity.
Factual has support for 30+ namespaces. You can see the detailed list here.
You can use Crosswalk to relate and aggregate content across web authorities, and mashup the best content from each.
Resolve lets you start with incomplete data you may have for an entity, and get out the full entity data, assuming Factual is able to make a high confidence match.
For example, say you know the name of a place and some imprecise location. The Java driver lets you use Resolve to get a single, high-quality match, like this:
This shows you Factual’s full record for the resolved entity as a Map, including its Factual ID:
name = Buena Vista Cigar Club,
region = CA,
status = 1,
tel = (310) 273-8100,
postcode = 90210,
country = US,
category = Shopping > Tobacco Shops,
resolved = false,
address = 9715 Santa Monica Blvd,
locality = Beverly Hills,
longitude = -118.407808,
latitude = 34.068735,
We hope you’ll find new and interesting uses for Factual, including Crosswalk and Resolve. If you end up releasing something interesting, please let us know so we can give you a shout-out!
Complete docs on how to install and use the Java driver are here. The driver itself is open source. The test suite includes integration tests as well as simple demos to illustrate usage. If you have any questions or suggestions, we hope you’ll contact us through the driver’s github project.
Factual’s service is currently in Beta, and you can obtain an API key here.