priceapi

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

400 Bad Request

{
  "job_id": "1234567890abcdef12345678",
  "status": "new",
  "requested": 2
}

{
  "success": false,
  "reason": "missing parameter",
  "parameter": "key",
  "comment": "Provide the mandatory parameter 'key'!"
}

{
  "success": false,
  "reason": "unauthorized",
  "parameter": "token",
  "comment": "Provide your API key with the parameter 'token'!"
}

Body Params

token

string

required

Your API key

source

string

required

Name of the data source to request from

country

string

required

Lower case alpha-2 country code of the source to request from

key

string

required

The type of identifier you want to use (source_id, gtin, keyword)

values

string

required

The identifiers you want to request, separated by newline characters

completeness

string

Prices may be paginated. How many pages do you want to request? (one_page, all_pages)

currentness

string

How current should the data be? (daily_updated, realtime)

Size limit

We limit the number of items that can be requested in a single job to 1,000. If you want to request more than 1,000 products, you can run multiple jobs in parallel.

JSON response

The only relevant information in the JSON response is the job_id. Save this value for steps 2 and 3.

Errors

An error is indicated by an HTTP status code in the 4xx and 5xx ranges. If the error happens on an application level, we try to provide an explanation in JSON.

Non-JSON responses

If something goes wrong somewhere deeper in our stack (say on a load balancer), we might return a different kind of response (like HTML or text).

Example error response

{
  "success": false,
  "reason": "unauthorized",
  "parameter": "token",
  "comment": "Provide your API key with the parameter 'token'!"
}

<html><body><h1>503 Service Unavailable</h1>
No server is available to handle this request.
</body></html>

List of error codes

Error code

Meaning

unauthorized

No token given or token is not valid.

missing parameter

Not all required parameters were given.

parameter value invalid

Given value is not allowed for this parameter.

unknown source

Chosen source is not supported (yet).

unsupported country

Chosen country is not supported for the chosen source.

unsupported key

Chosen key is not supported by the chosen source.

source disabled

Combination of source and country is temporarily disabled.

key disabled

Chosen key is temporarily disabled for this source and country.

value disabled

Chosen value is temporarily disabled for this source, country and key.

not enough free credits

Not enough free credits left for the given request, a paid subscription is needed.

daily quota exceeded

User-defined daily quota is exceeded. You can change this. See Daily quota.

too many values

Requested more than 1,000 values in one job.

completeness not allowed

Based on your plan, you are not allowed to use the requested completeness setting.

condition not allowed

Based on your plan, you are not allowed to use the requested conditionsetting.

Further error codes may be added.

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

/jobs/:job_id

Step 2: Request a job's status until it is finished.

gethttps://api.priceapi.com/jobs/job_id

# Assuming you stored your API key in environment variable PRICEAPI_TOKEN
curl https://api.priceapi.com/jobs/1234567890abcdef12345678?token=$PRICEAPI_TOKEN

require "rest-client" # gem install rest-client
require "json"

ENDPOINT = "https://api.priceapi.com"
job_id = "<the job_id from step 1>"

until ["finished", "cancelled"].include?(job_status)
  sleep 5 # In production, please use 30-60 seconds
  status_uri = URI("#{ENDPOINT}/jobs/#{job_id}?token=#{ENV["PRICEAPI_TOKEN"]}")
  status_response = Net::HTTP.get_response(status_uri)
  status_hash = JSON.parse(status_response.body)
  job_status = status_hash["status"]
  puts "Job #{job_id} status #{job_status}"
end

unless job_status == "finished"
  puts "Job #{job_id} terminated in status #{job_status}"
  exit 1
end

# TODO: Add logging, error handling, retries and metrics.

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 working

404 Not Found

200 finished

{
  "job_id": "1234567890abcdef12345678",
  // Wait until status is "finished".
  "status": "working",
  "progress": 50, // 0 to 100
  "requested": 2,
  "completed": 1
}

{
  "success": false,
  "reason": "job not found",
  "comment": "No job found for the given job id '1234567890abcdef12345678'!"
}

{
  "job_id": "1234567890abcdef12345678",
  // Wait until status is "finished".
  "status": "finished",
  // Progress can be 100 before.
  "progress": 100,
  "requested": 2,
  "completed": 2
}

Path Params

job_id

string

required

The id of a recently created job. Found in the JSON response of the create request.

Query Params

token

string

required

Your API key

List of status codes

Status code

Meaning

new

The job was just received and will be scheduled soon.

working

The job was scheduled and is being worked on according to the scheduling.

finishing

All data for the job has been collected and the results are being compiled.

finished

The job was processed completely and is ready to be downloaded.

cancelled

The job's processing was cancelled. It cannot be downloaded. No credits have been booked for this job.

Further status codes may exist or be added later.

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.

Further error codes may be added.

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

/products/bulk/:job_id

Step 3: Download a finished job's results.

gethttps://api.priceapi.com/products/bulk/job_id

# Assuming you stored your API key in environment variable PRICEAPI_TOKEN
# JSON is the default
curl -L https://api.priceapi.com/products/bulk/1234567890abcdef12345678?token=$PRICEAPI_TOKEN

# Explicitly select JSON
curl -L https://api.priceapi.com/products/bulk/1234567890abcdef12345678.json?token=$PRICEAPI_TOKEN
# Select XML
curl -L https://api.priceapi.com/products/bulk/1234567890abcdef12345678.xml?token=$PRICEAPI_TOKEN
# Select CSV, row-based (one row per offer with redundant products information)
curl -L https://api.priceapi.com/products/bulk/1234567890abcdef12345678.csv?token=$PRICEAPI_TOKEN&format_option=row
# select CSV, column based (one row per product, offers appended as columns)
curl -L https://api.priceapi.com/products/bulk/1234567890abcdef12345678.csv?token=$PRICEAPI_TOKEN&format_option=column

require "rest-client" # gem install rest-client
require "json"

ENDPOINT = "https://api.priceapi.com"
job_id = "<the job_id from step 1>"

result_uri =
  URI("#{ENDPOINT}/products/bulk/#{job_id}?token=#{ENV["PRICEAPI_TOKEN"]}")
result_response = Net::HTTP.get_response(result_uri)
if result_response.is_a?(Net::HTTPRedirection)
  result_response = Net::HTTP.get_response(URI(result_response["Location"]))
end
result_hash = JSON.parse(result_response.body)
puts JSON.pretty_generate(result_hash)

# TODO: Add logging, error handling, retries and metrics.

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

503 Service Unavailable

302 Found

{
  "job_id": "1234567890abcdef12345678",
  "status": "finished",
  // used test credits for this request
  "free_credits": 0,
  // used paid credits for this requests
  "paid_credits": 2,
  // array including multiple entries
  "products": [
    // Multiple products here (see below)
  ]
}

{
  "success": false,
  "reason": "job not finished",
  "comment": "The job with id '1234567890abcdef12345678' is not finished, yet! Status: finishing",
  "status": "finishing"
}

HTTP/1.1 302 Found
Location: https://api.priceapi.com/results/1234567890abcdef12345678.json?code=ABC123

Path Params

job_id

string

required

The id of a recently created job. Found in the JSON response of the create request.

Query Params

token

string

required

Your API key

format_option

string

May be row or column. Only when format is CSV.

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 row-based (recommended for Pivot Tables)
CSV columns

{
  "job_id": "1234567890abcdef12345678",
  "status": "finished",
  // used test credits for this request
  "free_credits": 0,
  // used paid credits for this requests
  "paid_credits": 2,
  // array including multiple entries
  "products": [
    {
      "source": "google-shopping",
      "country": "de",
      "key": "gtin",
      // the value in the same format as you requested it
      "value": "00885909666966",
      // true or false
      "success": true,
      // if success "false", see section about errors
      "reason": null,
      "id": "15858468867886681869",
      "name": "Apple iPad mini Wi-Fi 16 GB - Schwarz & Graphit",
      // ... other product attributes
      // array of offers found for this product
      "offers": [
        {
          "shop_name": "Some Shop",
          // As a string to avoid floating point rounding errors
          "price": "284.99",
          "price_with_shipping": "286.89",
          "shipping_costs": "1.90",
          // ISO 4217 currency code
          "currency": "EUR",
          // maybe more attributes, depending on the source
        },
        {
          "shop_name": "Another shop",
          "price": "289.82",
          // Not always shown
          "price_with_shipping": null,
          // Same here
          "shipping_costs": null,
          "currency": "EUR",
          // ...
        }
        // Several more offers...
      ]
    },
    {
      // More products
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <job-id>1234567890abcdef12345678</job-id>
  <status type="symbol">finished</status>
  <free-credits type="integer">0</free-credits>
  <paid-credits type="integer">2</paid-credits>
  <products type="array">
    <product>
      <source>google-shopping</source>
      <country>de</country>
      <key>gtin</key>
      <value>00885909666966</value>
      <success type="boolean">true</success>
      <id>15858468867886681869</id>
      <name>Apple iPad mini Wi-Fi 16 GB - Schwarz & Graphit</name>
      <brand-name>Apple</brand-name>
      <category-name>Tablet<category-name/>
      <review-count>37<review-count/>
      <review-rating>100<review-rating/>
      <gtins type="array">
        <gtin>00047165900004</gtin>
        <gtin>00885909575329</gtin>
        <gtin>00885909666881</gtin>
        <gtin>00885909666898</gtin>
        <gtin>00885909666966</gtin>
      </gtins>
      <url>https://www.google.de/shopping/product/15858468867886681869</url>
      <offers type="array">
        <offer>
          <shop-name>Some Shop</shop-name>
          <price>284.99</price>
          <price-with-shipping>284.99</price-with-shipping>
          <shipping-costs>0.00</shipping-costs>
          <currency>EUR</currency>
          <!-- maybe more attributes, depending on the source -->
        </offer>
        <offer>
          <shop-name>Another shop</shop-name>
          <price>289.82</price>
          <price-with-shipping nil="true"/>
          <shipping-costs nil="true"/>
          <currency>EUR</currency>
          <!-- maybe more attributes, depending on the source -->
        </offer>
        <!-- ... -->
      </offers>
    </product>
    <product>
      <!-- second product --->
    </product>
  </products>
</hash>

"source","country","key","value","success","reason","source_id","source_url","updated_at","gtins","eans","name","brand_name","category_name","review_count","review_rating","relevance","offer.url","offer.name","offer.price","offer.price_with_shipping","offer.shipping_costs","offer.position","offer.position_with_shipping","offer.availability_code","offer.availability_text","offer.shop_name"

"source","country","key","value","success","reason","source_id","source_url","updated_at","gtins","eans","name","brand_name","category_name","review_count","review_rating","relevance","offers[0].url","offers[0].name","offers[0].price","offers[0].price_with_shipping","offers[0].shipping_costs","offers[0].availability_code","offers[0].availability_text","offers[0].shop_name","offers[1].url","offers[1].name","offers[1].price","offers[1].price_with_shipping","offers[1].shipping_costs","offers[1].availability_code","offers[1].availability_text","offers[1].shop_name","offers[2].url",...

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.

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.

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

/jobs

Get a list of recently created jobs

gethttps://api.priceapi.com/jobs

cURL

# Assuming you stored your API key in environment variable PRICEAPI_TOKEN
curl https://api.priceapi.com/jobs?token=$PRICEAPI_TOKEN

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

[
  {
    "job_id": "1234567890abcdef12345678",
    "country": "pl",
    "source": "google-shopping",
    "status": "finished",
    "requested": 162,
    "refusals": 0,
    "timeouts": 0,
    "errors": 0,
    "created_at": "2017-11-20T17:31:18Z",
    "terminated_at": "2017-11-20T18:15:15Z",
    "downloaded_at": "2017-11-20T21:47:22Z"
  },
  // ...
]

Query Params

token

string

required

Your API key

page

int32

Page for pagination

per_page

int32

Number of jobs per page, maximum 1,000

Daily quota

Daily quota is a personal protective mechanism to reduce the potential harm of a defect integration.

Limitations

There are certain scenarios in which this mechanism does not work (e.g. multiple parallel jobs and high completeness parameters). Please see Daily quota in the documentation for more.

Disclaimer

We provide the daily quota to limit the potential harm that broken code could cause. Still, it is your responsibility to make sure, your access to the API is sound.

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

/settings/daily_quota

Request your daily quota setting

gethttps://api.priceapi.com/settings/daily_quota

cURL

# Assuming you stored your API key in environment variable PRICEAPI_TOKEN
curl https://api.priceapi.com/settings/daily_quota?token=$PRICEAPI_TOKEN

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

{
  "daily_quota": 10000
}

{
  "success": false,
  "reason": "unauthorized",
  "parameter": "token",
  "comment": "Provide your API key with the parameter 'token'!"
}

Query Params

token

string

required

Your API key

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

/settings/daily_quota

Change your daily quota setting

puthttps://api.priceapi.com/settings/daily_quota

cURL

# Assuming you stored your API key in environment variable PRICEAPI_TOKEN
curl -X PUT https://api.priceapi.com/settings/daily_quota \
  -d "token=$PRICEAPI_TOKEN" \
  -d 'kind=credits' \
  -d 'quota=7890'

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

400 Bad Request

{
  "success": true,
  "kind": "credits",
  "quota": 10000
}

{
  "success": false,
  "reason": "missing parameter",
  "parameter": "kind",
  "comment": "Provide the mandatory parameter 'kind'!"
}

{
  "success": false,
  "reason": "unauthorized",
  "parameter": "token",
  "comment": "Provide your API key with the parameter 'token'!"
}

Body Params

token

string

required

Your API key

kind

string

required

Has to be "credits"

quota

int32

required

The new quota, needs to be bigger than 0

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

/settings/monthly_included_usage

Request the monthly included usage in your current subscription

gethttps://api.priceapi.com/settings/monthly_included_usage

cURL

# Assuming you stored your API key in environment variable PRICEAPI_TOKEN
curl https://api.priceapi.com/settings/monthly_included_usage?token=$PRICEAPI_TOKEN

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

{
  "monthly_included_usage": 50000
}

{
  "success": false,
  "reason": "unauthorized",
  "parameter": "token",
  "comment": "Provide your API key with the parameter 'token'!"
}

Query Params

token

string

required

Your API key

Overview

Index of search Keys

Key

Description

gtin

Search by GTIN, EAN, UPC or JAN - this is the number represented by the barcode commonly printed on product packaging. See documentation on barcodes.

source_id

Search by the identifier given by the respective source. For Amazon, this is the ASIN.

keyword

Search by any search phrase, e.g. iPhone 6c.

asin

Amazon Standard Identification Number (ASIN)

part_no

Part number, issued by the manufacturer

Sources by country

We currently provide data in 23 countries: Australia, Austria, Belgium, Brazil, Canada, Czechia, Denmark, France, Germany, India, Italy, Japan, Mexico, Netherlands, Norway, Poland, Russian Federation, Spain, Sweden, Switzerland, Turkey, United Kingdom, and United States

Australia (`au`)

We currently provide data for Australia from 1 source:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Austria (`at`)

We currently provide data for Austria from 2 sources:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)
Idealo (idealo, with keys gtin, keyword, source_id, source_url)

Belgium (`be`)

We currently provide data for Belgium from 1 source:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Brazil (`br`)

We currently provide data for Brazil from 1 source:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Canada (`ca`)

We currently provide data for Canada from 2 sources:

Amazon (amazon, with keys gtin, keyword, source_id)
Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Czechia (`cz`)

We currently provide data for Czechia from 1 source:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Denmark (`dk`)

We currently provide data for Denmark from 1 source:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)

France (`fr`)

We currently provide data for France from 3 sources:

Amazon (amazon, with keys gtin, keyword, source_id)
Google Shopping (google-shopping, with keys gtin, source_id, keyword)
Idealo (idealo, with keys gtin, keyword, source_id, source_url)

Germany (`de`)

We currently provide data for Germany from 4 sources:

Amazon (amazon, with keys gtin, keyword, source_id)
billiger.de (billiger, with keys gtin, keyword, source_id, asin)
Google Shopping (google-shopping, with keys gtin, source_id, keyword)
Idealo (idealo, with keys gtin, keyword, source_id, source_url)

India (`in`)

We currently provide data for India from 2 sources:

Amazon (amazon, with keys gtin, keyword, source_id)
Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Italy (`it`)

We currently provide data for Italy from 3 sources:

Amazon (amazon, with keys gtin, keyword, source_id)
Google Shopping (google-shopping, with keys gtin, source_id, keyword)
Idealo (idealo, with keys gtin, keyword, source_id, source_url)

Japan (`jp`)

We currently provide data for Japan from 1 source:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Mexico (`mx`)

We currently provide data for Mexico from 2 sources:

Amazon (amazon, with keys gtin, keyword, source_id)
Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Netherlands (`nl`)

We currently provide data for Netherlands from 1 source:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Norway (`no`)

We currently provide data for Norway from 1 source:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Poland (`pl`)

We currently provide data for Poland from 1 source:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Russian Federation (`ru`)

We currently provide data for Russian Federation from 1 source:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Spain (`es`)

We currently provide data for Spain from 3 sources:

Amazon (amazon, with keys gtin, keyword, source_id)
Google Shopping (google-shopping, with keys gtin, source_id, keyword)
Idealo (idealo, with keys gtin, keyword, source_id, source_url)

Sweden (`se`)

We currently provide data for Sweden from 1 source:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Switzerland (`ch`)

We currently provide data for Switzerland from 1 source:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Turkey (`tr`)

We currently provide data for Turkey from 1 source:

Google Shopping (google-shopping, with keys gtin, source_id, keyword)

United Kingdom (`gb`)

We currently provide data for United Kingdom from 3 sources:

Amazon (amazon, with keys gtin, keyword, source_id)
Google Shopping (google-shopping, with keys gtin, source_id, keyword)
Idealo (idealo, with keys gtin, keyword, source_id, source_url)

United States (`us`)

We currently provide data for United States from 2 sources:

Amazon (amazon, with keys gtin, keyword, source_id)
Google Shopping (google-shopping, with keys gtin, source_id, keyword)

Amazon

We currently provide data on Amazon (amazon) for 9 countries. The data includes products and offers.

Supported countries:

Americas: Canada (ca), Mexico (mx), and United States (us)
Asia: India (in)
Europe: France (fr), Germany (de), Italy (it), Spain (es), and United Kingdom (gb)

Supported keys:

gtin
keyword
source_id

billiger.de

We currently provide data on billiger.de (billiger) for 1 country. The data includes products and offers.

Supported countries:

Europe: Germany (de)

Supported keys:

gtin
keyword
source_id
asin

Google Shopping

We currently provide data on Google Shopping (google-shopping) for 23 countries. The data includes products and offers.

Supported countries:

Americas: Brazil (br), Canada (ca), Mexico (mx), and United States (us)
Asia: India (in), Japan (jp), and Turkey (tr)
Europe: Austria (at), Belgium (be), Czech Republic (cz), Denmark (dk), France (fr), Germany (de), Italy (it), Netherlands (nl), Norway (no), Poland (pl), Russian Federation (ru), Spain (es), Sweden (se), Switzerland (ch), and United Kingdom (gb)
Oceania: Australia (au)

Supported keys:

gtin
source_id
keyword