Beta API Documentation

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.

For any API endpoints not listed on this page (e.g., V3 API endpoints), please refer to our V3 OAuth documentation and rely on our language-specific drivers for best results.

Authentication

In V4, server API calls are made by passing your API key into the KEY (case-sensitive) parameter, and making your requests through https:

https://api.factual.com/categories?KEY=your_API_key

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.


We’re still working on support for Android and client-side (Javascript/browser) access, so currently V4 APIs are unavailable to those platforms.

Tracking Throttle Allocation (Real-time)

Every API response includes the remaining throttle allocation for the specified API key in the X-Factual-Throttle-Allocation HTTP header.

Example:

X-Factual-Throttle-Allocation:{"burst":"0%","daily":"0%"}

Notes:

  • The Factual API has a requests per minute limit as well as a per day limit. Exceeding the requests per minute will result in a short delay in processing each request rather than denying requests. The delay will, in aggregate, result in your request volume to be no greater than the RPM limit.
  • Exceeding the RMD will result in a 429 response.
  • RPD and RPM are calculated by per individual request method.
  • RPD and RPM are calculated based on rolling 24 hour and 1 minute periods.

Categories

The Categories API call returns the full Factual places category taxonomy, in either a nested or flat format.

Syntax

Request categories using HTTPS GET:

https://api.factual.com/categories?options=[JSON options]&KEY=[your API key]

Examples

https://api.factual.com/categories?options={"lang":"en","format":"index"}
https://api.factual.com/categories?options={"lang":"en","format":"tree"}

Request Parameters

Parameter Name Description Examples
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.
options={"lang":"en"}
options={"lang":"en","format":"index"}
KEY Your API Key. For server to server access only. Access by the KEY parameter is restricted by IP address.
KEY=Q3iBjOES4h1mZcNCZyBmQFcYREdjylIucvB3r2oI

Response

options={"lang":“en”,“format”:"index"}
The index format will return all category data hashed to category Ids:

{
  "response":
  {
    "data":
    {
      "1":
      {
        "parents": [ ],
        "id": 1,
        "label": "Factual Places"
      },
      "2":
      {
        "parents": ["1"],
        "id": 2,
        "label": "Automotive"
      },
      .
      .
      .
   }
 }
 "status": "ok",
 "version": 4
}


options={"lang":“en”,“format”:"tree"}
The tree format will return the taxonometric list of categories, nested.

{
  "response":
  {
    "data":
    [
      {
        "id": 1,
        "label": "Factual Places",
        "children":
        [
          {
            "id": 2,
            "label": "Automotive",
            "children":
            [
              {
                "id": 3,
                "label": "Car Appraisers"
              },
              {
                "id": 4,
                "label": "Car Dealers and Leasing",
                "children":
                [
                  {
                    "id": 5,
                    "label": "Used Cars"
                  }
                ]
              },
              .
              .
              .
   ]
 }
 "status": "ok",
 "version": 4
}