Step 3: Download a finished job's results.

🚧

Follow redirects

For performance reasons, we sometimes pre-render your results. If we do so, we will respond with a redirect. Please make sure, your client follows redirects when you request results.

Result formats

We currently can give you the job results in four different formats:

  • JSON (recommended for integration)
  • XML
  • CSV (for most topics)
  • XSLX (for most topics)
{
  "job_id": "1234567890abcdef12345678",
  "status": "finished",
  "free_credits": 2,
  "paid_credits": 0,
  "results": [
    {
      "query": {
        "source": "test",
        "country": "us",
        "topic": "search_results",
        "key": "gtin",
        "value": "00885909666966",
        "max_pages": 1,
        "max_age": 1200
      },
      "success": true,
      "metadata": {
        "from_cache": false,
        "page_count_delivered": 2,
        "page_count_from_cache": 0,
        "page_count_live": 2,
        "request_count": 3,
        "updated_at": "2017-06-08T12:34:37Z",
        "tag": "2017_06_01-10_03_51"
      },
      "content": {
        "search_results": [
          {
            "id": "product_0",
            "updated_at": "2017-06-08 12:34:37 UTC",
            "url": "https://test.priceapi.com/products/product_0",
            "name": "00885909666966 Result 0"
          },
          {
            "id": "product_1",
            "updated_at": "2017-06-08 12:34:37 UTC",
            "url": "https://test.priceapi.com/products/product_1",
            "name": "00885909666966 Result 1"
          },
            // ... more search results
        ]
      }
    },
    // ... next search
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <job-id>1234567890abcdef12345678</job-id>
  <status type="symbol">finished</status>
  <free-credits type="integer">2</free-credits>
  <paid-credits type="integer">0</paid-credits>
  <results type="array">
    <result>
      <query>
        <source>test</source>
        <country>us</country>
        <topic>search_results</topic>
        <key>gtin</key>
        <value>00885909666966</value>
        <max-pages type="integer">1</max-pages>
        <max-age type="integer">1200</max-age>
      </query>
      <success type="boolean">true</success>
      <metadata>
        <from-cache type="boolean">false</from-cache>
        <page-count-delivered type="integer">2</page-count-delivered>
        <page-count-from-cache type="integer">0</page-count-from-cache>
        <page-count-live type="integer">2</page-count-live>
        <request-count type="integer">3</request-count>
        <updated-at type="dateTime">2017-06-08T12:34:37Z</updated-at>
      </metadata>
      <content>
        <search-results type="array">
          <search-result>
            <id>product_0</id>
            <updated-at type="dateTime">2017-06-08T12:34:37Z</updated-at>
            <url>https://test.priceapi.com/products/product_0</url>
            <name>00885909666966 Result 0</name>
          </search-result>
          <search-result>
            <id>product_1</id>
            <updated-at type="dateTime">2017-06-08T12:34:37Z</updated-at>
            <url>https://test.priceapi.com/products/product_1</url>
            <name>00885909666966 Result 1</name>
          </search-result>
            <!-- ... more search results -->
        </search-results>
      </content>
    </result>
    <!-- ... next search -->
  </results>
</hash>

🚧

72 hour retention period

Job results are only available for 72 hours after the job was requested. After that we permanently delete the results. So please make sure to download the results shortly after the job finishes.

List of error codes

Error code

Meaning

unauthorized

No token given or token is not valid.

job not found

No job could found for given job_id.

job forbidden

User with given token is not allowed access to the given job.

job not finished

Job processing is still in progress. Wait until its status it is finished.

Further error codes may be added.

Product-level errors

Even when a job is accepted, there may be errors while collecting data on individual products. This is indicated with the success attribute being false and with a given reason attribute.

When an error occurs, we don't deduct any credits. The only exception is for reason not found (see below) as this is a valid response and it takes us the same amount of effort to find this out.

List of reasons

Reason codes

Meaning

not found

We have successfully searched for the given product, but it is not currently present on the source.

invalid value

We have checked the value and found that it is invalid. We did not try to request this. For example, if you search with key=gtin we will check the provided GTIN's checksum.

validation error

We failed to collect valid data for you.

timeout

We could not collect the data in the timespan allowed by you. See job parameter timeout.

source temporary not reachable

We cannot collect data from this source at the moment.

offer not found

A product was found, but it does not currently have any offers.

failed to access source

We cannot collect data from this source at the moment.

cluster not found

Data for the product could not be collected at this time. We expect to be able to collect the data next time you request it.

cluster_gone

Data for the product could not be collected at this time. We have to search for it, which may take a while. We may be able to collect the data next time you request it (generally within the next days).

not_searchable

Data for the product could not be collected and we estimated that we cannot do so in the near future.

to_be_searched

Data for the product could not be collected at this time. We have to search for it, which may take a while. We may be able to collect the data next time you request it (generally within the next days).

error

General error in our processing.

Further reasons may exist or be added later.

Language
Authentication
Query
Response
Click Try It! to start a request and see the response here!