Introduction
Welcome SimpleGeo customers. As you may have heard, SimpleGeo has shut down their local data services. We hope this guide will make transitioning to Factual easy and pain free.
There are free levels of API access provided. We charge a CPM-based fee for premium API access. Complete terms of service are available here. If you require premium API access please contact Factual.
Basic Technical Differences
First, there are several similarities:
- SimpleGeo 1.2 already serves up Factual data and therefore includes Factual IDs.
- Both SimpleGeo's and Factual's APIs use 2-legged OAuth 1.0 for authentication.
- Both SimpleGeo's and Factual's APIs are based on a RESTful model.
- Both SimpleGeo's and Factual's APIs return data in JSON.
Notable differences:
- Factual is an open-ended data platform: our queries are intended to support use cases outside of Place data. As such, you may find that queries are more verbose than you are used to.
- Factual's V3 API does not currently support write capabilities. The ability to add and edit places is coming very soon, however.
- Factual's V3 API does not currently support "private" places.
Convert Your OAuth Credentials
- SimpleGeo and Factual both use 2-legged OAuth 1.0, so switching to Factual's authentication should just be a matter of switching your key and secret.
- Request a Factual v3 Key here.
- You can find additional details including code examples and drivers here.
Convert Your IDs
SimpleGeo Places 1.0 to Factual
You can use our Crosswalk API to convert your SimpleGeo Places 1.0 IDs to Factual IDs
Basic Syntax
Example
Convert the SimpleGeo 1.0 ID to a Factual ID.
SimpleGeo 1.0 ID: SG_6Cnx1RsOAHRxqNiRvEFY57
Run example - NOTE: We're in the process of converting our Crosswalk data from SimpleGeo Handles to SimpleGeo IDs. The process is scheduled to complete end of day 1-12-2012. Until then, the query above will return zero rows. Thanks for your patience!
You can find more documentation on our Crosswalk API here.
SimpleGeoPlaces 1.2 to Factual
Your SimpleGeo ID IS a Factual ID! SimpleGeo partnered with Factual this past June, and began incorporating Factual global places data into their Places 1.2 API.
In the example below, the Factual ID is "afcfa085-7ceb-4c28-a367-aabd2d1e1618":
Convert Your Queries
The data
We currently offer access to 55 million place entities in 49 countries through a single unified API. SimpleGeo 1.2 already uses the Factual dataset, including Factual Place Categories. Place attributes are mostly the same, but please see our Global Places Attributes for specifics.
Searching for places
Factual is a general data platform so our queries are intended to support use cases outside of Place data. Therefore we provide the same Places Search functionality as SimpleGeo, plus some additional search features.
Example Queries
| Query Type | SimpleGeo | Factual |
|---|---|---|
| Geo | ||
| Search | ||
| Category | ||
| Using OR with Categories | ||
| Pagination |
Category handling in Factual
If you are using SimpleGeo's 1.2 API, you'll find that each place is defined using the exact same categories as Factual.
Of note, Factual categories are three levels deep. Not all places will use all three levels of categorization. For example, you may find a place categorized as "Food & Beverage". You may find another place more specifically categorized as "Food & Beverage > Restaurants" and you may find yet other places categorized all the way down to "Food & Beverage > Restaurants > Barbecue".
You can find all places of a specific category using the equals operator:
Alternately, you can find all places of a specific category AND all places belonging to children of that category using the begins with operator:
Unsupported Features
- At the current time, Factual does not support "private" places as SimpleGeo 1.0 does.
- V3 of the Factual API will be supporting user contributed places and corrections to places in Q1 of 2012.
Additional Resources
For additional support please visit our Developer Forum.