idealo click report API documentation

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:

Obtain OAuth 2.0 Credentials from idealo business
Obtain an access-token from https://businessapi.idealo.com/api/v1/oauth/token
Do an API request
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.

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.

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.

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.

Path

Type

Optional

Description

from

String

false

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

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>