Product Data with Node.js and CSV
For this guide, we're going to assume the following you're interested in using Datafiniti's product data to analyze trends in the women's luxury shoe market. Let's say you're a data scientist that's been tasked with the following:
- Collect pricing data on women's luxury shoes from multiple online retailers.
- Sort the data by brand.
- Determine the average price of each brand.
Your environment and data needs:
- You're working with Node.js.
- You want to work with CSV data.
Here are the steps we'll take:
1. Install the request module for Node
In your terminal, run the following to install the request
module for Node:
npm install request
2. Get your API token
The next thing you'll need is your API token. The API token lets you authenticate with Datafiniti API and tells it who you are, what you have access to, and so on. Without it, you can't use the API.
To get your API token, go the Datafiniti Web Portal (https://portal.datafiniti.co), login, and click your settings in the left navigation bar. From there, you'll see a page showing your token. Your API token will be a long string of letters and numbers. Copy the API token or store it somewhere you can easily reference.
For security reasons, your API token will be automatically changed whenever you change your password.
For the rest of this document, we'll use
AAAXXXXXXXXXXXX
as a substitute example for your actual API token when showing example API calls.
.
3. Run your first search
The first thing we'll do is do write some code that will run a test search. This test search will give us a sense for what sort of data might be available. Eventually we'll refine our search so that we get back the most relevant data.
Since we want hotels, let's try a simple search that will just give us online listings for hotels.
Write the following code in your code editor (replace the dummy API token with your real API token):
/*
Illustrates an API call to Datafiniti's Business Database for hotels.
*/
var request = require('request');
// Set your API parameters here.
var API_token = 'AAAXXXXXXXX';
var format = 'JSON';
var query = 'categories:shoes';
var num_records = 1;
var download = false;
var request_options = {
url: 'https://api.datafiniti.co/v4/products/search',
method: 'POST',
json: {
'query': query,
'format': format,
'num_records': num_records,
'download': download
},
headers: {
'Authorization': 'Bearer ' + API_token,
'Content-Type': 'application/json'
}
}
console.log(request_options);
// Make the API call.
request(request_options, function(error, response, body) {
if (error) {
console.log(error);
console.log(response);
} else {
console.log(body);
}
});
You should get a response similar to this:
{
"num_found": 884885,
"total_cost": 1,
"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": "AVkzMzokUmTPEltRlaJ_"
}
]
}
Let's break down each of the parameters we sent in our request:
API Call Component | Description |
---|---|
"query": "categories:shoes" | query tells the API what query you want to use. In this case, you're telling the API you want to search by categories . Any product that has shoes listed in its categories field will be returned. |
"num_records": 1 | num_records tells the API how many records to return in its response. In this case, you just want to see 1 matching record. |
Now let's dive through the response the API returned:
Response Field | Description |
---|---|
"num_found" | The total number of available records in the database that match your query. If you end up downloading the entire data set, this is how many records you'll use. |
"total_cost" | The number of credits this request has cost you. Product records only cost 1 credit per record. |
"records" | The first available matches to your query. If there are no matches, this field will be empty. Within each record returned, you'll see multiple fields shown. This is the data for each record. |
Within the records
field, you'll see a single product returned with multiple fields and the values associated with that product. The JSON response will show all fields that have a value. It won't show any fields that don't have a value.
Each product record will have multiple fields associated with it. You can see a full list of available fields in our Product Data Schema.
4. Refine your search
If you take a look at the sample record shown above, you'll notice that it's not actually a pair of shoes. It's actually a shirt. It was returned as a match because its category keywords included Clothing, Shoes & Jewelry
. If we downloaded all matching records, we would find several products that really are shoes, but we'd also find other products like this one, which aren't.
We'll need to refine our search to make sure we're only getting shoes. Modify your code to look like this:
/*
Illustrates an API call to Datafiniti's Product Database.
*/
var request = require('request');
// Set your API parameters here.
var API_token = 'AAAXXXXXXXX';
var format = 'JSON';
var query = 'categories:shoes AND -categories:shirts AND categories:women AND (brand:* OR manufacturer:*) AND prices:*';
var num_records = 10;
var download = false;
var request_options = {
url: 'https://api.datafiniti.co/v4/products/search',
method: 'POST',
json: {
'query': query,
'format': format,
'num_records': num_records,
'download': download
},
headers: {
'Authorization': 'Bearer ' + API_token,
'Content-Type': 'application/json'
}
}
console.log(request_options);
// Make the API call.
request(request_options, function(error, response, body) {
if (error) {
console.log(error);
console.log(response);
} else {
console.log(body);
}
});
This code is different in a couple ways:
- It uses
AND -categories:shirts
to filter out any products that might be shirts. Note the-
in front ofcategories
. - It adds
AND categories:women
to narrow down results to just products for women. (We were interested in just women's shoes.) - It adds
AND (brand:* OR manufacturer:*)
. This ensures thebrand
ormanufacturer
field is filled out in all the records I request. We call the*
a "wildcard" value. Matching against a wildcard is a useful way to ensure the fields you're searching aren't empty. - It adds
AND prices:*
. Again, matching against a wildcard here means we're sure to only get products that have pricing information. - It changes
records=1
torecords=10
so we can look at more sample matches.
Notice how Datafiniti lets you construct very refined boolean queries. In the API call above, we're using a mix of AND
and OR
to get exactly what we want.
If you would like to narrow your search to just exact matches you can place the search term in quotation marks.
/*
Illustrates an API call to Datafiniti's Product Database.
*/
var request = require('request');
// Set your API parameters here.
var API_token = 'AAAXXXXXXXX';
var format = 'JSON';
var query = 'name:"Apple Iphone 10"';
var num_records = 10;
var download = false;
var request_options = {
url: 'https://api.datafiniti.co/v4/products/search',
method: 'POST',
json: {
'query': query,
'format': format,
'num_records': num_records,
'download': download
},
headers: {
'Authorization': 'Bearer ' + API_token,
'Content-Type': 'application/json'
}
}
console.log(request_options);
// Make the API call.
request(request_options, function(error, response, body) {
if (error) {
console.log(error);
console.log(response);
} else {
console.log(body);
}
});
The above query will only return products with the exact name of Apple Iphone 10.
5. Initiate a download of the data
Once we like what we see from the sample matches, it's time to download a larger data set! To do this, we're going to update our code a fair bit (an explanation follows):
/*
Illustrates an API call to Datafiniti's Product Database.
*/
var request = require('request');
var fs = require('fs');
// Set your API parameters here.
var API_token = 'AAAXXXXXXXX';
var view_name = 'product_flat_prices';
var format = 'CSV';
var query = 'categories:shoes AND -categories:shirts AND categories:women AND (brand:* OR manufacturer:*) AND prices:*';
var num_records = 50;
var download = true;
var request_options = {
url: 'https://api.datafiniti.co/v4/products/search',
method: 'POST',
json: {
'query': query,
'num_records': num_records,
'view': view_name,
'format': format,
'download': download
},
headers: {
'Authorization': 'Bearer ' + API_token,
'Content-Type': 'application/json'
}
}
console.log(request_options);
// A function to check if a download request has completed
function checkDownloadUntilComplete(options, callback) {
var download_id = options.download_id;
var download_options = {
url: 'https://api.datafiniti.co/v4/downloads/' + download_id,
method: 'GET',
headers: {
'Authorization': 'Bearer ' + API_token,
'Content-Type': 'application/json'
}
}
request(download_options, function(error, response, body) {
var num_files_downloaded = 0;
var download_response = JSON.parse(body);
console.log('Records downloaded: ' + download_response.num_downloaded);
if (download_response.status !== 'completed') {
// NEED A SLEEP FUNCTION HERE!
checkDownloadUntilComplete(options, callback);
} else {
var results = download_response.results;
console.log(results);
for (var i = 0; i < results.length; i++) {
var filename = download_id + '_' + i + '.' + format;
var file = fs.createWriteStream(filename);
request(results[i]).pipe(file).on('end', function() {
console.log('File ' + (i+1) + ' out of ' + results.length + ' saved: ' + filename);
num_files_downloaded++;
if (num_files_downloaded === results.length) process.exit();
});
}
}
});
}
// Initiate the download request.
request(request_options, function (error, response, body) {
var request_response = body;
var download_id = request_response.id;
// Check on status of the download request.
checkDownloadUntilComplete ({download_id : download_id}, function (error, response) {});
}
);
A few things to pay attention to in the above code:
- We changed
format
fromJSON
toCSV
. We'll want to view the files in CSV format, so it will be easier to look at. - We change
num_records
from10
to50
. This will download the first 50 matching records. If we wanted to download all matching records, we would removenum_records
.num_records
will tell the API to default to all available records. - We set
view
toproduct_flat_prices
. This will nest fields like categories and features into a single cell, while splitting each price for a product into its own row. - We changed
download
fromfalse
totrue
.
If num_records is not specified, ALL of the records matching the query will be downloaded.
Since we've handled multiple steps of the download process in this code, we won't go into the details here, but we do recommend you familiarize yourself with those steps. Checking them out in our Product Data with Postman and CSV guide.
When using the API, you will not receive any warning if you are going past your monthly record limit. Keep a track on how many records you have left by checking your account. You are responsible for any overage fees if you go past your monthly limit.
6. Open the result file(s) in Excel
The download code will save one or more result files to your project folder. Open one of those files in Excel. It will look something like:
7. Analyze the results
Using Excel, we can find the average price of all these shoes, by averaging the columns for prices.amountMin
or prices.amoundMax
. When I do this in my file, I get 75.825
as the average price. Your average will probably be slightly different, since you're downloading the data at a different time than I did.
Updated about 1 year ago