NAV
shell python ruby

Introduction

The Datafiniti Aurora API is set up to be RESTful. The goal was to develop an API that has intuitive and logical URLs and use the HTTP response codes as much as possible to indicate API errors. By utilizing the standard HTTP header fields, we are able to provide a robust experience that can be interpreted using any available HTTP client. While most calls will result in a JSON response, when requesting data we provide the option to specify a format.

Resources

Overview

Resource Usage
data The primary resource in the Datafiniti Aurora API, Data and its sub-resources allow you to preview and download specific data.
users This resource allows for the creation, modification, and viewing of users.
requests This resource provides information on started downloads.
results A resource that represents the posted results for a download.

End Points

# => Data Types
# /v3/data/businesses
# /v3/data/products

# => Check request status
# /v3/requests/asd750934f

# => Get your user information
# /v3/users/asdf1234asdf1234asdf1234

# => Get result URLs for a given request
# /v3/results/asd750934f
# => Data Types
# /v3/data/businesses
# /v3/data/products

# => Check request status
# /v3/requests/asd750934f

# => Get your user information
# /v3/users/asdf1234asdf1234asdf1234

# => Get result URLs for a given request
# /v3/results/asd750934f
# => Data Types
# /v3/data/businesses
# /v3/data/products

# => Check request status
# /v3/requests/asd750934f

# => Get your user information
# /v3/users/asdf1234asdf1234asdf1234

# => Get result URLs for a given request
# /v3/results/asd750934f

https://api.datafiniti.co/

Resource URL Patterns

Authentication

Usage

# With shell, you can pass your token appended with a colon as the user option
curl "https://api.datafiniti.co/v3/requests/request_id" -u your_api_token:

# you can also just pass the correct header with each request
export API_TOKEN=your_api_token
export ENCODED_API_TOKEN="$(echo "$API_TOKEN:" | base64)"
# note that the added : needs to be added prior to encoding as shown above
curl "https://api.datafiniti.co/v3/requests/request_id" -H "Authorization: $ENCODED_API_TOKEN"
import requests
import json
API_TOKEN = 1jrhf6gk0d8dfg0dgfd1kkg9

s = requests.Session()
s.auth = (API_TOKEN, '')

s.get('https://api.datafiniti.co/v3/resource/')
# Authenticate with HTTP Basic
require 'rest-client'

api = RestClient::Resource.new("https://api.datafiniti.co", "YOUR_API_TOKEN", "")
api.get "v3/requests/1234567"

# You can pass the authorization header to your REST client gem
require 'faraday'
require 'base64'
API_TOKEN = your_api_token
ENCODED_API_TOKEN = Base64.encode("#{API_TOKEN}:")

api = Faraday.new(:url => "https://api.datafiniti.co") do |req|
  req.headers['Authorization'] = ENCODED_API_TOKEN
end

api.get "/v3/requests/1234567"

We use API Tokens to authenticate to the Datafiniti Aurora API. After registering for a plan you should have received an API Token. Alternatively, your token can be viewed from the “My Account” page on the Datafiniti website. The API Token allows use of all available credits in your account, make sure to keep it secret.

The Datafiniti Aurora API uses HTTP Basic Auth for authentication. The API Token is used as the username and the password is left blank.

Data

export API_TOKEN=your_api_token
curl "/v3/data/businesses?view=businessList_all_json=*" -u $API_TOKEN
curl "/v3/data/businesses?view=products_all_json=*" -u $API_TOKEN
require 'rest-client'

api = RestClient::Resource.new("https://api.datafiniti.co", "YOUR_API_TOKEN", "")

api.get("/v3/data/businesses?view=businessList_all_json=*")
api.get("/v3/data/businesses?view=products_all_json=*")
import requests
import json
API_TOKEN = your_api_token

api = requests.Session()
api.auth = (API_TOKEN, '')

api.get("https://api.datafiniti.co/v3/data/businesses?view=businessList_all_json=*")
api.get("https://api.datafiniti.co/v3/data/businesses?view=products_all_json=*")

To download or preview data you must make a call to the /v3/data/{DATA_TYPE} resource.

Endpoint

/v3/data/{DATA_TYPE}

Data Types

Type Description
businesses Contains business and location data.
products Contains product data. This may contain description, pricing, and review data.
properties Contains property data. This may contain prices, amenities, and agents.

See the following schemas:

Required Parameters

Parameter Description
q The query string. Uses Solr syntax. This string contains the filters you want to use to narrow down your search. The query string must be URL encoded, and any forward slashes must be escaped with a back slash.
view The view defines exactly how you want the data to be formatted. It specifies which fields to return, the order of the fields, and whether to return as a CSV or JSON. At this time, only JSON is available. We provide some generic views to begin with and we are currently working on setting up a method for users to generate their own views. If you would like a specific format, please contact us.

Examples

# Examples
export API_RESOURCE='https://api.datafiniti.co'
curl '$API_RESOURCE/v3/data/businesses?view=businessList_all_json&q=name:data*'
curl '$API_RESOURCE/v3/data/businesses?view=businessList_all_json&q=province:(TX CA)'
curl '$API_RESOURCE/v3/data/businesses?view=businessList_all_csv&q=website:["" to *]'
curl '$API_RESOURCE/v3/data/businesses?view=businessList_all_json&q=name:Datafiniti OR province:TX'

# Async
export API_TOKEN='1134sdfsfdjbjjgjglambo984mvmj'
export API_RESOURCE='https://$API_TOKEN:@api.datafiniti.co'
curl '$API_RESOURCE/v3/businesses?q=name:Marty McFly Sneaker Co&view=businessReviews_all_json&async=true'

# Records
export API_TOKEN='1134sdfsfdjbjjgjglambo984mvmj'
export API_RESOURCE='https://$API_TOKEN:@api.datafiniti.co'
curl '$API_RESOURCE/v3/businesses?q=name:Marty McFly Sneaker Co&view=businessReviews_all_json&records=100500'
import requests
import json
API_TOKEN = your_api_token

s = requests.Session()
s.auth = (API_TOKEN, '')

s.get('/v3/data/businesses?view=businessList_all_json&q=name:data*')
s.get('/v3/data/businesses?view=businessList_all_csv&q=province:(TX CA)')
s.get('/v3/data/businesses?view=businessList_all_json&q=website:["" to *]')
s.get('/v3/data/businesses?view=businessList_all_csv&q=name:Datafiniti OR province:TX')

# Parameters
import requests
import json
API_TOKEN = your_api_token

s = requests.Session()
s.auth = (API_TOKEN, '')

# Async
s.get('https://api.datafiniti.co/v3/businesses?q=name:Marty McFly Sneaker Co&view=businessReviews_all_json&async=true')

# Records
s.get('https://api.datafiniti.co/v3/businesses?q=name:Marty McFly Sneaker Co&view=businessReviews_all_json&records=100500')
require 'rest-client'

API_TOKEN = your_api_token

response = JSON.parse(RestClient.get('https://API_TOKEN:@api.datafiniti.co/v3/data/businesses?view=businessList_all_json&q=name:Datafiniti OR province:TX'))
Description Solr Query
All businesses that include variations of data in their name q=name:data*
All businesses in California and Texas q=province:(TX CA)
All businesses that have a website q=website:[“” to *]
All businesses where name is Datafiniti or located in Texas q=name:Datafiniti OR province:TX

Available Views

Available JSON views are:

Available CSV views are:

You can GET a list of all views available to your account by performing a GET request to https://api.datafiniti.co/v3/views.

Optional Paramters

Async

```python
import requests
import json
API_TOKEN = your_api_token

s = requests.Session()
s.auth = (API_TOKEN, '')

s.get('https://API_TOKEN:@api.datafiniti.co/v3/businesses?q=name:Marty McFly Sneaker Co&view=businessReviews_all_json&async=true')
```ruby
# Async
require 'rest-client'

API_TOKEN = your_api_token

response = RestClient.get('https://API_TOKEN:@api.datafiniti.co/v3/businesses?q=name:Marty McFly Sneaker Co&view=businessReviews_all_json&async=true')
object = JSON.parse(response)

# Records
require 'rest-client'

API_TOKEN = your_api_token

response = RestClient.get('https://API_TOKEN:@api.datafiniti.co/v3/businesses?q=name:Marty McFly Sneaker Co&view=businessReviews_all_json&records=100500')
object = JSON.parse(response)

To generate a download for the query, add the paramter async=true. This will return a download ID. To return a preview of your results (default 10 items) set async=false or omit the paramter.

Records


The number of records you would like the query to return. This number of records will be debited from your available downloads.

Users

Get User Data

curl "https://api.datafiniti.co/v3/users/<your_api_token>" -u your_api_token:
# the final : after your_api_token is required
import requests
import json
API_TOKEN = your_api_token

s = requests.Session()
s.auth = (API_TOKEN, '')

s.get("https://api.datafiniti.co/v3/users/{0}".format(API_TOKEN))
require 'rest-client'

API_TOKEN = your_api_token

response = RestClient.get("https://#{API_TOKEN}:@api.datafiniti.co/v3/users/#{API_TOKEN}")
object = JSON.parse(response)

Example Response JSON Object

{
  "token": "api_token",
  "plan": "100000M",
  "available_downloads": 100000,
  "email": "test@test.com",
  "organization": "Datafiniti",
  "first_name": "Bob",
  "last_name": "Deysarker",
  "phone_number": "555-555-5555",
  "active": 1,
  "date_registered": "2013-07-09T21:56:01Z"
}

End point

GET /v3/users/{USER_API_TOKEN}

Returns all user data pertaining to that user in a JSON format.

Common Codes

HTTP Code Description
200 The user data was returned successfully
401 The API token is not authenticated to view this user
404 The API token provided does not exist
503 The API is currently down.

Attributes

Key Type Value
token string The API Token associated with the user
organization string The organization associated with the user if provided.
email string The email associated with the user.
first_name string The first name of the user if provided.
last_name string The last name of the user if provided.
phone_number string The phone number of the user if provided.
plan_id string The plan associated with this user.
active boolean If the user currently has an active plan.
available_downloads integer the number of download credits remaining for an active account
date_registered date The date the account was first created, this date will be used to determine when more credits are added on a monthly basis.

Errors

HTTP Status Code Summary

HTTP Code Status Meaning
200 OK Request was successful
204 OK Request was successful, but no data was returned (This is expected behavior)
400 Bad Request Often times a missing or incorrect parameter
401 Unauthorized Invalid/Missing API Token
404 Not Found Using an invalid API end point, or the user supplied path is incorrect
422 Unprocessable Entity All the parameters were correct but the request was rejected on the back end, contact support with request information
523 Service Unavailable The API is currently unavailable due to maitenance, try again later.
5xx Server Error There was an error within the Datafiniti servers