Datafiniti API

The Datafiniti Developer Hub

Welcome to the Datafiniti Developer Hub. Here you'll find comprehensive guides and documentation to help you start using the Datafiniti API as quickly as possible. Let's get some data!

Get Started    
Suggest Edits

data/products

 
gethttps://api.datafiniti.co/v3/data/products
curl --user AAAXXXXXXXXXXXX: 'http://api.datafiniti.co/v3/data/products?view=products_all&format=JSON&q=categories:shoes&records=1&download=false'
<?php
// Set your API parameters here.
$APIToken = 'AAAXXXXXXXXXXXX';
$view = 'products_all';
$format = 'JSON';
$query = urlencode('categories:shoes');
$records = '1';
$download = 'false';

// Construct the API call.
$APICall = 'https://' . $APIToken . ':@api.datafiniti.co/v3/data/products?'
			. 'view=' . $view 
			. '&format=' . $format
			. '&q=' . $query
			. '&records=' . $records 
			. '&download=' . $download;

// Make the API call.
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_URL, $APICall);
$response = curl_exec($ch);

// Do something with the response.
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) == 200) {
	$response = json_decode($response, true);

	print_r($response);
} else {
	echo "Request failed.";
}

?>
var request = require('request');

// Set your API parameters here.
var APIToken = 'AAAXXXXXXXXXXXX';
var view = 'products_all';
var format = 'JSON';
var query = encodeURIComponent('categories:shoes');
var records = '1';
var download = 'false';

// Construct the API call.
var APICall = 'https://' + APIToken + ':@api.datafiniti.co/v3/data/products?'
				+ 'view=' + view
				+ '&q=' + query
				+ '&format=' + format
				+ '&records=' + records
				+ '&download=' + download;

// Make the API call.
request(
  {
    url : APICall
  },
  // Do something with the response.
  function (error, response, body) {
  	console.log(body);
  }
);
import requests
import urllib.parse
import json

# Set your API parameters here.
APIToken = 'AAAXXXXXXXXXXXX'
view = 'products_all'
format = 'JSON'
query = urllib.parse.quote_plus('categories:shoes')
records = '1'
download = 'false'

# Construct the API call.
APICall = 'https://' + APIToken + ':@api.datafiniti.co/v3/data/products?' \
			+ 'view=' + view \
			+ '&format=' + format \
			+ '&q=' + query \
			+ '&records=' + records \
			+ '&download=' + download

# Make the API call.
r = requests.get(APICall);

# Do something with the response.
if r.status_code == 200:
	print(json.loads(r.content))
else:
	print('Request failed')
{
  "estimated total": 884885,
  "records": [
    {
      "asins": [
        "B010XYTFM6"
      ],
      "brand": "inktastic",
      "categories": [
        "Novelty",
        "Tops & Tees",
        "Novelty & More",
        "Women",
        "Clothing, Shoes & Jewelry",
        "T-Shirts",
        "Clothing"
      ],
      "dateAdded": "2015-11-09T01:55:09Z",
      "dateUpdated": "2016-04-12T16:19:26Z",
      "imageURLs": [
        "http://ecx.images-amazon.com/images/I/41W6xSgsBbL._SX342_QL70_.jpg",
        "http://ecx.images-amazon.com/images/I/41StiamgorL._SR38,50_.jpg",
        "http://ecx.images-amazon.com/images/I/41StiamgorL._SX342_QL70_.jpg",
        "http://ecx.images-amazon.com/images/I/41W6xSgsBbL._SR38,50_.jpg"
      ],
      "keys": [
        "inktasticwomensbutterflybanjochickjuniorvnecktshirts/b010xytfm6"
      ],
      "name": "Inktastic Women's Butterfly Banjo Chick Junior V-neck T-shirts",
      "sourceURLs": [
        "http://www.amazon.com/Inktastic-Womens-Butterfly-Junior-T-Shirts/dp/B010XYTK1W",
        "http://www.amazon.com/Inktastic-Womens-Butterfly-Junior-T-Shirts/dp/B016HKYYN0",
        "http://www.amazon.com/Inktastic-Butterfly-T-Shirts-Athletic-Heather/dp/B016HKYPYS"
      ]
    }
  ]
}
[
  {
    "id": 6073,
    "records": "",
    "query": "categories:shoes",
    "dataType": "products",
    "dataFormat": "csv",
    "accountId": "AAAXXXXXXXXXXXX",
    "planId": "free",
    "view": "products_all",
    "async": 1,
    "status": "STARTED",
    "error": "",
    "numDownloaded": 0,
    "numFound": 884885,
    "numRequested": 884885,
    "date_started": "2017-1-11 15:52:42",
    "date_completed": "2017-1-11 15:52:43"
  }
]

Query Params

view
string

Determines which fields will be returned. See all available views.

format
string

csv for CSV-formatted data. json for JSON-formatted data.

download
boolean

false to see a real-time preview. true to initiate a download.

records
int32

The number of products you want returned. Set it to a blank value if you want all products returned. If download is set to false and records is left blank, then a default value of 10 will be used.

q
string

A search query that specifies what data to return. Use the product schema to see which fields you can query on.

 

The data endpoint lets you run preview searches and initiate downloads for product data.

Returns

If you set download=false, the data/products API call will return a list of matching products for your query.

If you set download=true, it will return a request object that can be used to monitor the status of the download request.

Response Codes and Messages

Response Code
Error Message
What You Should Do

200

N/A

Everything worked! You should check out the awesome data you just requested.

400

field name does not exist in product schema

Make sure you're using the correct name for a field. Consult the product data schema for available fields.

400

invalid query

Your query syntax has a mistake somewhere. Check what you're setting for q for any mistakes.

400

view does not exist

Make sure you're using the correct value for view. See a list of available views.

401

N/A

You're using an invalid API token. Check out your account page on the Datafiniti Portal to make sure you have the right token.

 
gethttps://api.datafiniti.co/v3/requests
curl --user AAAXXXXXXXXXXXX: 'http://api.datafiniti.co/v3/requests/XXXX'
<?php

// Set your API parameters here.
$APIToken = 'AAAXXXXXXXXXXXX';
$requestID = '6073';

// Construct the API call.
$APICall = 'https://' . $APIToken . ':@api.datafiniti.co/v3/requests/' . $requestID;

// Make the API call.
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_URL, $APICall);
$response = curl_exec($ch);

// Do something with the response.
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) == 200) {
	$response = json_decode($response, true);

	print_r($response);
} else {
	echo "Request failed.";
}

?>
var request = require('request');

// Set your API parameters here.
var APIToken = 'AAAXXXXXXXXXXXX';
var requestID = 6073;

// Construct the API call.
var APICall = 'https://' + APIToken + ':@api.datafiniti.co/v3/requests/' + requestID;

// Make the API call.
request(
  {
    url : APICall
  },
  // Do something with the response.
  function (error, response, body) {
  	console.log(body);
  }
);
import requests
import urllib.parse
import json

# Set your API parameters here.
APIToken = 'AAAXXXXXXXXXXXX'
requestID = '6073'

# Construct the API call.
APICall = 'https://' + APIToken + ':@api.datafiniti.co/v3/requests/' + requestID

# Make the API call.
r = requests.get(APICall);

# Do something with the response.
if r.status_code == 200:
	print(json.loads(r.content))
else:
	print('Request failed')
[
  {
    "id": 6073,
    "records": "",
    "query": "categories:shoes",
    "dataType": "products",
    "dataFormat": "csv",
    "accountId": "AAAXXXXXXXXXXXX",
    "planId": "free",
    "view": "products_all",
    "async": 1,
    "status": "STARTED",
    "error": "",
    "numDownloaded": 0,
    "numFound": 884885,
    "numRequested": 884885,
    "date_started": "2017-1-11 15:52:42",
    "date_completed": "2017-1-11 15:52:43"
  }
]

Path Params

request_id
string
required

A number that uniquely identifies each download request.

 

The requests endpoint lets you monitor the status of a download you requested.

Returns

A requests object with the following fields:

Response Field
Description

id

A unique identifier for the request.

records

query

The query you ran.

dataType

The data type you queried.

dataFormat

The data format you requested.

accountID

Your API token.

planID

The Datafiniti plan level you're using.

view

The view you chose. This determines which fields are shown in the data.

async

Should always be set to 1. Indicates this is a download request.

status

The current progress of the request. As the download request is running, this will be set to STARTED. When it's done, it will be set to COMPLETED.

error

An error message in case anything went wrong with the download. Hopefully this is blank!

numDownloaded

The number of records that have been downloaded so far.

numFound

The number of total records in Datafiniti that matched your query.

numRequested

The number of records you requested to download.

date_started

The date and time the download started.

date_completed

The date and time the download finished.

Response Codes and Messages

Response Code
Error Message
What You Should Do

200

N/A

Everything worked! You should be looking at a download request object, which tells you the status of your download.

400

N/A

You might be trying to look at an invalid request ID. Check to make sure you're using a relevant ID. You can see all of your requests by calling /requests/ without an ID.

401

N/A

You're using an invalid API token. Check out your account page on the Datafiniti Portal to make sure you have the right token.

 
gethttps://api.datafiniti.co/v3/results
curl --user AAAXXXXXXXXXXXX: 'http://api.datafiniti.co/v3/results/XXXX'
<?php

// Set your API parameters here.
$APIToken = 'AAAXXXXXXXXXXXX';
$requestID = '6073';

// Construct the API call.
$APICall = 'https://' . $APIToken . ':@api.datafiniti.co/v3/results/' . $requestID;

// Make the API call.
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_URL, $APICall);
$response = curl_exec($ch);

// Do something with the response.
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) == 200) {
	$response = json_decode($response, true);

	print_r($response);
} else {
	echo "Request failed.";
}

?>
var request = require('request');

// Set your API parameters here.
var APIToken = 'AAAXXXXXXXXXXXX';
var requestID = 6073;

// Construct the API call.
var APICall = 'https://' + APIToken + ':@api.datafiniti.co/v3/results/' + requestID;

// Make the API call.
request(
  {
    url : APICall
  },
  // Do something with the response.
  function (error, response, body) {
  	console.log(body);
  }
);
import requests
import urllib.parse
import json

# Set your API parameters here.
APIToken = 'AAAXXXXXXXXXXXX'
requestID = '6073'

# Construct the API call.
APICall = 'https://' + APIToken + ':@api.datafiniti.co/v3/results/' + requestID

# Make the API call.
r = requests.get(APICall);

# Do something with the response.
if r.status_code == 200:
	print(json.loads(r.content))
else:
	print('Request failed')
[
  {
    "id": 120138,
    "url": "http://datafiniti-downloads-qa.s3.amazonaws.com/AAAXXXXXXXXXXXX/6073_1.csv?AWSAccessKeyId=AKIAIXQMCWHOZB3O35SA&Signature=2YtBsW9xY8CZrWDECcdLzyx4Jlk%3D&Expires=1484754763",
    "request_id": 6073,
    "downloaded": 0,
    "imported": 0,
    "date_created": "2017-1-11"
  }
]

Path Params

request_id
string
required

A number that uniquely identifies each download request.

 

The results endpoint lets you view the URLs of available data files for your download.

Returns

A list of results objects. Each result object has the following fields:

Response Field
Description

id

A unique identifier for the result object.

url

The URL of the data file. Fetch the content of this URL to download the file.

request_id

A unique identifier for your download request.

downloaded

An internal field. You can ignore this.

imported

An internal field. You can ignore this.

date_created

The date the result file was created. The result file will expire 7 days after this date.

Response Codes and Messages

Response Code
Error Message
What You Should Do

200

N/A

Everything worked! You should be looking at a list of result file objects, which contain URLs you can use to download the data files.

401

N/A

You're using an invalid API token. Check out your account page on the Datafiniti Portal to make sure you have the right token.

404

N/A

You're trying to access results that don't exist. If your download request status still says STARTED, then you need to wait until it says COMPLETED. You may also be using the wrong request ID.

500

N/A

You may be trying to look at an invalid request ID. Check to make sure you're using a relevant ID. You can see all of your requests by calling /requests/ without an ID.

gethttps://api.datafiniti.co/v3/users
curl --user AAAXXXXXXXXXXXX: 'http://api.datafiniti.co/v3/users/AAAXXXXXXXXXXXX'
<?php

// Set your API parameters here.
$APIToken = 'AAAXXXXXXXXXXXX';

// Construct the API call.
$APICall = 'https://' . $APIToken . ':@api.datafiniti.co/v3/users/' . $APIToken;

// Make the API call.
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_URL, $APICall);
$response = curl_exec($ch);

// Do something with the response.
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) == 200) {
	$response = json_decode($response, true);

	print_r($response);
} else {
	echo "Request failed.";
}

?>
var request = require('request');

// Set your API parameters here.
var APIToken = 'AAAXXXXXXXXXXXX';

// Construct the API call.
var APICall = 'https://' + APIToken + ':@api.datafiniti.co/v3/users/' + APIToken;

// Make the API call.
request(
  {
    url : APICall
  },
  // Do something with the response.
  function (error, response, body) {
  	console.log(body);
  }
);
import requests
import urllib.parse
import json

# Set your API parameters here.
APIToken = 'AAAXXXXXXXXXXXX'

# Construct the API call.
APICall = 'https://' + APIToken + ':@api.datafiniti.co/v3/users/' + APIToken

# Make the API call.
r = requests.get(APICall);

# Do something with the response.
if r.status_code == 200:
	print(json.loads(r.content))
else:
	print('Request failed')
{
  "token": "AAAXXXXXXXXXXXX",
  "organization": "Acme Inc",
  "email": "your@acme.com",
  "first_name": "Bugs",
  "last_name": "Bunny",
  "phone_number": "555-555-5555",
  "plan_id": "free",
  "type": "user",
  "active": 1,
  "available_downloads": 9831200,
  "date_registered": "2016-12-31"
}

Path Params

your_api_token
string
required
 

The users endpoint lets you view the status of your Datafiniti account.

Returns

A list of results objects. Each result object has the following fields:

Response Field
Description

token

Your API token

organization

Your organization or company.

email

Your email address.

first_name

Your first name.

last_name

Your last name.

phone_number

Your phone number.

plan_id

The Datafiniti plan to which you're subscribed.

type

Your account type. Should be set to user.

active

Whether or not your account is active.

available_downloads

The number of records you can download at this time.

date_registered

The date your account was created.