priceapi

Suggest Edits

Request process overview

Three steps to the data you need

 

Getting data is a three-step process:

  1. First you submit a job that specifies which data you want. As a result, you receive a job_id.
  2. Then you wait for the job to finish. You can request the job's status until it is finished.
  3. When the job is finished, you can download the job's results in a format you choose.
Suggest Edits

/jobs

Step 1: Create a new job.

 

Query Auth

 Authentication is required for this endpoint.
posthttps://api.priceapi.com/jobs
# Assuming you stored your API key in environment variable PRICEAPI_TOKEN
curl -X POST https://api.priceapi.com/jobs \
    -d "token=$PRICEAPI_TOKEN" \
    -d 'source=google-shopping' \
    -d 'country=de' \
    -d 'key=gtin' \
    -d 'values=00885909666966
               08718108041581'
require "uri"
require "net/http"
require "json"

ENDPOINT = "https://api.priceapi.com"

create_response = Net::HTTP.post_form(
  URI("#{ENDPOINT}/jobs"),
  token: ENV["PRICEAPI_TOKEN"],
  source: "google-shopping",
  country: "us", # alpha-2 country code, but lower-case
  key: "keyword",
  values: ["apple iphone 6S 64GB gold"].join("\n")
)
create_hash = JSON.parse(create_response.body)
job_id = create_hash["job_id"]
job_status = create_hash["status"]
puts "Created job #{job_id}"

# TODO: Add logging, error handling, retries and metrics.
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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.

Suggest Edits

/jobs/:job_id

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

 

Query Auth

 Authentication is required for this endpoint.
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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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.

Suggest Edits

/products/bulk/:job_id

Step 3: Download a finished job's results.

 

Query Auth

 Authentication is required for this endpoint.
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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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.

Suggest Edits

/jobs

Get a list of recently created jobs

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.priceapi.com/jobs
# 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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ 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

 
Suggest Edits

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.

Suggest Edits

/settings/daily_quota

Request your daily quota setting

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.priceapi.com/settings/daily_quota
# 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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ 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

 
Suggest Edits

/settings/daily_quota

Change your daily quota setting

 

Query Auth

 Authentication is required for this endpoint.
puthttps://api.priceapi.com/settings/daily_quota
# 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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "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

 
Suggest Edits

/settings/monthly_included_usage

Request the monthly included usage in your current subscription

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.priceapi.com/settings/monthly_included_usage
# 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

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ 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

 
Suggest Edits

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:

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:

Brazil (br)

We currently provide data for Brazil from 1 source:

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:

Denmark (dk)

We currently provide data for Denmark from 1 source:

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:

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:

Norway (no)

We currently provide data for Norway from 1 source:

Poland (pl)

We currently provide data for Poland from 1 source:

Russian Federation (ru)

We currently provide data for Russian Federation from 1 source:

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:

Switzerland (ch)

We currently provide data for Switzerland from 1 source:

Turkey (tr)

We currently provide data for Turkey from 1 source:

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)
Suggest Edits

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
Suggest Edits

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
Suggest Edits

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
Suggest Edits

Idealo

 

We currently provide data on Idealo (idealo) for 6 countries. The data includes products and offers.

Supported countries:

  • Europe: Austria (at), France (fr), Germany (de), Italy (it), Spain (es), and United Kingdom (gb)

Supported keys:

  • gtin
  • keyword
  • source_id
  • source_url