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.image: API key manager, accessible from your profile when you are logged into www.factual.com.

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.