Factual is releasing a new set of APIs based on a faster, easier to use API stack and providing some great new capabilities. The endpoints listed on this page (which will be continually updated) are currently available under beta.
If you hit any bugs while using these beta products, feel free to either contact your account manager directly, or use our standard support forum.
Note: the authentication mechanism below is for our Beta APIs only.
In V4, server API calls are made by passing your API key into the KEY (case-sensitive) parameter, and making your requests through https:
Instead of cryptographically signing your requests to verify that requests are being made by your service, as is required by our V3 API, you restrict IP addresses that are authorized to make API calls using your key (server-side), or restrict access by Bundle Id (iOS).
If you do not bind your key to an IP address or Bundle Id, you may be responsible for any unauthorized access to your API key.
image: API key manager, accessible from your profile when you are logged into www.factual.com.
Every API response includes the remaining throttle allocation for the specified API key in the X-Factual-Throttle-Allocation HTTP header.
The Categories API call returns the full Factual places category taxonomy, in either a nested or flat format.
Request categories using HTTPS GET:
|options||A set of options for rendering the output of the taxonomy. Currently, the valid options are lang and format. Supported languages are German (de), English (en), Spanish (es), French (fr), Italian (it), Japanese (jp), Korean (kr), Portuguese (pt), Chinese (zh), and Traditional Chinese (zh_hant). Supported formats are tree and index.|
|KEY||Your API Key. For server to server access only. Access by the KEY parameter is restricted by IP address.|
The index format will return all category data hashed to category Ids:
The tree format will return the taxonometric list of categories, nested.