Migrating from V3 to V4

On December 15 2017, we'll be launching V4 of our API. V4 has been designed from the ground up to provide more control and flexibility to developers. It also updates the "UX" of our API to conform to current API best practices.

V4 does have a few significant changes, with at least one of which requiring our users to substantively rework any Datafiniti API integration they have in place already. While V3 will remain online for a while, we are encouraging all users to migrate to V4 as quickly as possible. This guide will outline the changes you need be aware of and provides links to additional information to make the migration as easy as possible.

Auth is now handled in the Authorization header

Authenticating with the V4 API is no longer handled in the URL. Instead, it's handled in the Authorization header you send with your request.

In order to authenticate with the API, you need to send a header value for Authorization set to Bearer your_token.

For example, here's how a V3 API request looks in Postman:

Here's the same request in the V4 API:

POSTing searches instead of GETing searches

The biggest change in V4 is that searching for or downloading data now requires submitting a POST request instead of a GET request.

If you're unfamiliar with the differences between POST and GET, you can think of it this way: a GET request is like going to a URL in your web browser, while a POST request is like submitting a form on a website.

Our V4 documentation provides several examples of how to issue search and download requests:

/requests and /results condensed to just /downloads

We have removed the /results endpoint in the V4 API. Previously in the V3 API, you would need to make a request to /results/your_download_id to fetch the result file links for your download request. You no longer need to do this. Instead, the result file links are automatically displayed as part of the downloads endpoint as soon as they're available for a download.

Creating your own views

The V4 API gives users the ability to create their own custom views for the fist time.

As a reminder, views specify which fields are returned in your search or download request and how those fields are formatted. For example, the products_basicFields view for product data only returns a subset of available product fields, while the products_pricesFlat view will split multiple prices for a single product into different rows when requesting CSV data.

With the V4 API, you can create your own views. This can be done either before issuing a search request or during the search request. We've provided documentation for how to do either of these:

Creating your own view
Using a custom view during your search request