Introduction

The Factual API is using 2-legged OAuth 1.0.

Keys and Secrets

Because Factual is using 2-legged OAuth (versus 3-legged OAuth), you'll be making OAuth connections with only the OAuth "consumer" key and token. Your resulting Authorization header will contain the oauth_consumer_key and oauth_signature (generated from your secret) but will not contain an oauth_token parameter.  

For example (line feeds for clarity only):

Although the RFC for OAuth specifies providing the OAuth protocol parameters in the query part of the request (see section 5.2, bullet point #3), Factual only supports receiving the OAuth protocol parameters through the Authorization header currently.

When you are ready to start coding, you can get your API key and secret here.

Don't publish your secret! Your key and secret are used to cryptographically sign your request such that Factual can verify that the request came from you. Both are required in order to sign a request. Because one can't be used without the other, it is OK to have your consumer key in plain-text. On the other hand you should NEVER share your consumer secret or plain-text embed it in client-side code. If you accidentally expose your consumer secret, you should generate a new one from inside your Factual account in a timely manner.

Examples

We have fully supported drivers (your best bet!), code examples, and other wisdom for connecting to Factual in many languages here.

Helpful Hints

• For debugging purposes, you can make a limited number of requests to the Factual API without using OAuth. Simply pass your OAuth key with your API request using the KEY parameter.  Unsigned API requests cannot take advantage of any custom rate limits or offset restrictions.
• If you are attempting to create signed OAuth requests by hand, try the Apigee console.
• If you want to generate reference signatures to check your code against, give Google's Javascript OAuth signer a spin. Just be sure to leave token and token secret blank.