GuidesAPI Reference
Start using Price API

Technical migration guide

Your fastest way from version 1 to version 2

👍

Use the test datasource

To make things easier for you, we have added a test data source that behaves like the amazon data source, but only pretends to cost you credits.

New endpoints

While the three-step process (create a job, poll its status, download the results) is still the same, there are three new versioned endpoints for this process:

  1. /v2/jobs
  2. /v2/jobs/:job_id
  3. /v2/jobs/:job_id/download

New parameter topic

Version 2 is all about flexibility. While you could only request products and the offers attached to them in version 1, this is now only one of the many kinds of information Price API can collect for you. In addition, we supply search results, reviews, bestsellers and more. You can choose the kind of information to collect with the new mandatory parameter topic.

To make things easier for customers migrating from version 1, we support a topic product_and_offers that behaves very similar to what you are used to from version 1.

New key names id and term

In version 2, the key source_id has been renamed to just id and keyword has been renamed to term.

New JSON and XML response structure

We took the time to tidy up our response structures with the goal to make it more readable and intuitive for you.

At the root level, the response will only have a few attributes concerning the job:

{
  "job_id": "5a3008a0e4dd586e77a2b89a",
  "status": "finished",
  "free_credits": 1,
  "paid_credits": 0,
  "results": [ ... ]
}

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <job-id>5a3005360ef4ae2d61005716</job-id>
  <status type="symbol">finished</status>
  <free-credits type="integer">1</free-credits>
  <paid-credits type="integer">0</paid-credits>
  <results type="array"><!-- ... --></results>
<hash>

The results attribute contains an array of objects, one entry for each value requested in the job. They each hold four to five attributes:

  • query states your request
  • success indicates true exactly when we successfully collected data
  • optionally reason if it was not successful
  • metadata including information on how the job was processed
  • and content holding the data collected

Here's an example:

"results": [
  {
    "query": {
      "source": "google_shopping",
      "country": "de",
      "topic": "offers",
      "key": "id",
      "value": "2680289002714187668",
      "max_pages": 1,
      "max_age": 1200,
      "sort_by": "ranking_descending",
      "condition": "any",
      "shipping": "any"
    },
    "success": true,
    "metadata": {
      "from_cache": false,
      "page_count_delivered": 1,
      "page_count_from_cache": 0,
      "page_count_live": 1,
      "request_count": 1,
      "updated_at": "2017-12-12T16:49:40Z"
    },
    "content": { ... }
  },
  // More results ...
]

<results type="array">
  <result>
    <query>
      <source>google_shopping</source>
      <country>de</country>
      <topic>offers</topic>
      <key>id</key>
      <value>2680289002714187668</value>
      <max-pages type="integer">1</max-pages>
      <max-age type="integer">1200</max-age>
      <sort-by>ranking_descending</sort-by>
      <condition>any</condition>
      <shipping>any</shipping>
    </query>
    <success type="boolean">true</success>
    <metadata>
      <from-cache type="boolean">false</from-cache>
      <page-count-delivered type="integer">1</page-count-delivered>
      <page-count-from-cache type="integer">0</page-count-from-cache>
      <page-count-live type="integer">1</page-count-live>
      <request-count type="integer">27</request-count>
      <updated-at type="dateTime">2017-12-12T16:36:13Z</updated-at>
    </metadata>
    <content><!-- ... --></content>
  </result>
  <!-- More results -->
</results>

The content attribute can hold an array for lists of things or an object or null. Here's an example:

"content": {
  "total_offer_count": 63,
  "offers": [
    {
      "price": "349.0",
      "shipping_costs": "0.0",
      "price_with_shipping": "349.0",
      "currency": "EUR",
      "shop_name": "some-example-shop.com",
      "shop_id": "7935878264",
      "shop_review_count": 667,
      "shop_review_rating": 94,
      // ...
    },
    // More offers ...
  ]
}

<content>
  <total-offers-count type="integer">63</total-offers-count>
  <offers type="array">
    <offer>
      <price>349.0</price>
      <price-with-shipping>349.0</price-with-shipping>
      <shipping-costs>0.0</shipping-costs>
      <currency>EUR</currency>
      <shop-name>saturn.de</shop-name>
      <shop-matching-id>t3.media01.eu</shop-matching-id>
      <shop-review-count type="integer">667</shop-review-count>
      <shop-review-rating type="integer">94</shop-review-rating>
	    <!-- ... -->
    </offer>
    <!-- More offers -->
  </offers>
</content>

Success

In version 2, we return "success": true exactly then, when we could access the data source and collect data from it.

We also return true now when we successfully searched for a product and it was not present on the source. In version 1, this was reported as "success": false, "reason": "not found". This will come with a content value of null (if the content is usually represented as an object) or empty array [] (if the content is usually represented as an array).

Use the timeout parameter

For some use cases, you would prefer to receive partial data instead of waiting longer. To support this, we introduced a new parameter that allows you to determine after how many minutes a job's data collection should end.

A job that runs in a timeout will change to status finished and can then be downloaded and processed like any other job. It will include some results marked as "success": false, "reason": "timeout".

📘

Default timeout

If you don't specify otherwise, we have set a default of 1,440 minutes (24 hours).

Did we miss anything?

Please get in contact so we can help you out and so that we can improve our documentation.