Introduction

Factual currently returns all data as JSON.

Sample Response

This is a typical Factual API response to a read request:

Things to note:

• All fields are identified using lower-cased field names, with underscores as necessary.
• If you use the select parameter, the fields will be returned using the alias or name that you selected. Otherwise, the canonical field name will be used.
• If Factual has no data for a field in a row, the field will not be present. In the example above, Factual has no age on record for Madonna. That doesn't mean she is ageless- just that Factual doesn't know her age.
• If Factual has explicit knowledge that the proper value for a field is for it to be blank, it may appears as "". In the example above, Factual believes Madonna should not have a last name.
• Some requests include total_row_count. This is helpful when paging through data, as (when combined with included_rows) it can tell you if there are other rows that can be requested using offsets and limits.

Unlike previous versions of the Factual API, requests that result in error responses no longer return HTTP 200 status codes. Instead, they return the HTTP error code appropriate to the error condition. In all cases, the response will still contain more specific error messages. It is highly recommended that you utilize a JSON parsing library that will enable you to access the body of the HTTP response, even if the response yields a non-200 status.

More complete documentation on error responses from the Factual API can be found here.