General

idealo Business API to get detailed click reports (asynchronously) and daily click reports (synchronously).

The base address of the API in production is: https://businessapi.idealo.com

Authentication

Credentials

To access the API you need a client id and a client secret. You can generate some new credentials in idealo business, under 'My idealo' → 'Settings' → 'API clients' → 'idealo business API'.

Note
The client secret is only shown once at creation time! If you have no longer access or forgot your client secret, please create new credentials and delete the old one.

OAuth2 steps

The idealo business APIs are secured by OAuth2. At a high level, you follow four steps:

  1. Obtain OAuth 2.0 Credentials from idealo business

  2. Obtain an access-token from https://businessapi.idealo.com/api/v1/oauth/token

  3. Do an API request

  4. The access token expires after 3600 seconds and you need get a new access-token like before.

Get Access Token

POST /api/v1/oauth/token

Returns the access token for the idealo Business API. You need to provide the access token for every secured endpoint in the API.

Request headers

Header Type Optional Description

Authorization

Object

false

The client credentials client id and secret.

Response fields

Path Type Optional Description

access_token

String

false

The access-token that is used for authentication. You need to provide it in the authorization header when you fetch data from the api.

token_type

String

false

The tokens type. In this case it’s bearer.

expires_in

Integer

true

The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. You need to fetch a new token when it is expired.

scope

String

false

The scopes for this token.

shop_id

Integer

true

The shopId the access-token is valid for.

Example request

$ curl 'https://businessapi.idealo.com/api/v1/oauth/token' -i -u '51f060d4-7893-4dd5-975f-8566ff5ece60:Y0ur-Cl13nt-S3cr3t' -X POST

Example response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 868

{
  "access_token" : "eyJraWQiOiJ0ZXN0LWtleS1pZCIsImFsZyI6IlJTMjU2In0.eyJqdGkiOiIxYTdhZDhmYS05NjFkLTQ2YmYtYTU3NS01OTcyNTNmYzg4MGQiLCJpc3MiOiJhdXRob3JpemF0aW9uc2VydmVyIiwiaWF0IjoxNjYwNTczNjkxLCJleHAiOjE2NjA1NzQ2OTEsImF1ZCI6ImJ1c2luZXNzYmFja2VuZCIsImF1dGhvcml0aWVzIjpbIlJPTEVfRVhURVJOQUxfQ0xJRU5UIl0sInNjb3BlIjpbIkJVU0lORVNTQkFDS0VORDpDUkVBVEVfT0ZGRVJSRVBPUlQiLCJCVVNJTkVTU0JBQ0tFTkQ6UkVBRF9QRVJGT1JNQU5DRVJFUE9SVCIsIkJVU0lORVNTQkFDS0VORDpDUkVBVEVfUFJJQ0VSRVBPUlQiLCJCVVNJTkVTU0JBQ0tFTkQ6Q1JFQVRFX0NMSUNLUkVQT1JUIiwiQlVTSU5FU1NCQUNLRU5EOlJFQURfT0ZGRVJSRVBPUlQiLCJCVVNJTkVTU0JBQ0tFTkQ6UkVBRF9QUklDRVJFUE9SVCIsIkJVU0lORVNTQkFDS0VORDpSRUFEX0NMSUNLUkVQT1JUIiwiQlVTSU5FU1NCQUNLRU5EOkNSRUFURV9QRVJGT1JNQU5DRVJFUE9SVCJdLCJjbGllbnRfaWQiOiI0Y2U5ZjJiNC1mNDg5LTQxYWEtYWFjOS1jYjE3MjNjNTliNjMiLCJzaG9wX2lkIjoxfQ.VTduD6hCUtWNYf8KubFyvGEtFYr2CXse1mTRlRvNUEXwGgqgpL0IHxY-irdxENwhv4HoeW_lXFH8XQrk_55wYJn7im2cUkXCllo9lYBa9mKRPCq8dq2yv8mD3bShBnmrKiSDt3_-NgE2Xt2Xo0YqiY9YAkztQxjjeeDnjcSWULeBDRgxx2w7IYe6yLk5T8mevGWiTUkN48vLPNkH2zJSW1n3EQm41DqTEjTX2Dqn-ENcdVWyUliY8fMqAB6CGveAfKqHW4PL-iMU4f7q_pJDkxGJFibN9Kl9wBTLGGjzxfuU5tsrwUwaHd2spEQt0C0DZG9bOprFiZXTqVOB8lg-zg",
  "token_type" : "bearer",
  "expires_in" : 3600,
  "scope" : "BUSINESSBACKEND:CREATE_PRICEREPORT,BUSINESSBACKEND:READ_PRICEREPORT",
  "shop_id" : 1
}

Click report operations

Start Report

POST /api/v1/shops/{shopId}/click-reports

Triggers the creation of a new report for the specified shop id and parameters. If a report is already in progress for the specified shop id an error (409) will be thrown.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

The shop id.

Request fields

Path Type Optional Description

from

String

false

Start date of the time frame for which the data should be processed.

to

String

false

End date of the time frame for which the data should be processed.

Response fields

Path Type Optional Description

status

String

true

The status of the report.

Must be one of [PROCESSING, FAILED, SUCCESSFUL].

startTime

String

true

The time when the report has been started.

endTime

String

true

The time when the report has finished.

id

String

true

The report id.

shopId

Integer

true

The shop id of the report.

from

String

true

Start date of the time frame for which the data should be processed.

to

String

true

End date of the time frame for which the data should be processed.

Example request

$ curl 'https://businessapi.idealo.com/api/v1/shops/12345/click-reports' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJraWQiOiJ0ZXN0LWtleS1...' \
    -d '{"from":"2017-01-01","to":"2017-01-02"}'

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "status" : "PROCESSING",
  "id" : "d689c50d-82ac-4aff-8a3a-4ca6eee2d42b",
  "shopId" : 12345,
  "from" : "2017-10-01",
  "to" : "2017-10-02"
}

Get Report

GET /api/v1/shops/{shopId}/click-reports/{reportId}

Returns the report for the specified report id.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

The shop id.

reportId

Object

false

The report id.

Response fields

Path Type Optional Description

status

String

true

The status of the report.

Must be one of [PROCESSING, FAILED, SUCCESSFUL].

startTime

String

true

The time when the report has been started.

endTime

String

true

The time when the report has finished.

id

String

true

The report id.

shopId

Integer

true

The shop id of the report.

from

String

true

Start date of the time frame for which the data should be processed.

to

String

true

End date of the time frame for which the data should be processed.

Example request

$ curl 'https://businessapi.idealo.com/api/v1/shops/12345/click-reports/d689c50d-82ac-4aff-8a3a-4ca6eee2d42b' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJraWQiOiJ0ZXN0LWtleS1...'

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status" : "SUCCESSFUL",
  "startTime" : "2017-12-22T15:07:49.795Z",
  "endTime" : "2017-12-22T15:08:04.394Z",
  "id" : "d689c50d-82ac-4aff-8a3a-4ca6eee2d42b",
  "shopId" : 12345,
  "from" : "2017-10-01",
  "to" : "2017-10-02"
}

Download Report

GET /api/v1/shops/{shopId}/click-reports/{reportId}/download

Downloads the report for the specified report id.

Path parameters

Parameter Type Optional Description

shopId

Integer

false

The shop id.

reportId

Object

false

The report id.

Example request

$ curl 'https://businessapi.idealo.com/api/v1/shops/12345/click-reports/d689c50d-82ac-4aff-8a3a-4ca6eee2d42b/download' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJraWQiOiJ0ZXN0LWtleS1...'

Example response

HTTP/1.1 200 OK
Content-Disposition: attachment; filename=report_detailed_clicks_2017-10-01_2017-10-02.csv.zip
Content-Type: application/octet-stream

<binary>

Daily click report operations

Download Daily Click Report

GET /api/v1/shops/{shopId}/daily-click-reports/download

Path parameters

Parameter Type Optional Description

shopId

Integer

false

Query parameters

Parameter Type Optional Description

from

String

true

Start date of the time frame for which the data should be processed.

e.g. from=2019-05-01

to

String

true

End date of the time frame for which the data should be processed.

e.g. to=2019-05-01

Example request

$ curl 'https://businessapi.idealo.com/api/v1/shops/12345/daily-click-reports/download?from=2018-05-15&to=2018-05-21' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJraWQiOiJ0ZXN0LWtleS1...'

Example response

HTTP/1.1 200 OK
Content-Disposition: attachment; filename=report_daily_clicks_2018-05-15_2018-05-21.csv
Content-Type: application/octet-stream

<binary>