Introduction
Factual provides a very robust infrastructure for serving data to you. It's scalable, and delivers high performance. We're trying to make sure that it stands up to whatever you throw at it.
That said, for the time being, we need to set some basic limitations for users. It is, after all, being provided for free!
Basics
Factual API requests are variably throttled in the following ways:
- Burst limit - maximum requests per minute
- Daily limit - maximum requests per day
- Row limit - when reading data, the maximum number of rows that can be paged into.
- Page size limit - when reading data, maximum number of rows that can be returned in a single request
A couple things to note on row and page size limits:
- Increasing page size will adversely affect performance of your requests.
- The row limit affects the combination of the offset and limit parameters in read calls. Offset + limit can never exceed the row limit. For example, if you set your offset to 451 and you set your limit to 50, one of the rows you are attempting to access is the 501st row. If your row limit is 500, this will result in an HTTP 403 error code.
- The spirit of API requests is to provide as much data as a reasonable end user would consume. In other words, each request is intended to provide a page of data that your actual end user would interact with. If you are using the API to consume very large numbers of rows at a time, you are probably using the wrong tool. For use cases that require caching large quantities of data, Factual provides downloads of data.
Default limits
Default limits are assigned based on whether or not your request has been signed using 2-legged OAuth. Factual accepts unsigned requests primarily for diagnostic purposes. For any requests that will be serviced at higher volumes, you must sign your requests.
For signed OAuth requests, the defaults below are simply a starting point. If you sign your request, you may contact Factual directly for a higher allocation as required.
API method | unsigned | OAuth signed | ||||||
burst | daily | rows | page size | burst | daily | rows | page size | |
|---|---|---|---|---|---|---|---|---|
crosswalk | 60 | 100 | 500 | 50 | 300 | 500 | 500 | 50 |
| geocode | 60 | 100 | 500 | 50 | 300 | 10,000 | 500 | 50 |
| geopulse | 60 | 100 | 500 | 50 | 300 | 10,000 | 500 | 50 |
| read | 60 | 100 | 500 | 50 | 300 | 10,000 | 500 | 50 |
resolve | 60 | 100 | NA | NA | 300 | 100 | NA | NA |
* Note that the figures above aren't intended as a service level agreement. Especially during beta, access to the API may be subject to maintenance downtime. Furthermore, keys that are generating an extraordinary number of syntax errors or traffic that appears abusive to the system may be temporarily or permanently disabled to ensure better access for other users.