This is the API powering Omnia 2.0 and Pricemonitor, containing operations which can also be used directly by customers from their own systems.
This is the API powering Omnia 2.0 and Pricemonitor, containing operations which can also be used directly by customers from their own systems.
The Omnia 2.0 API is RESTful and provides access to the backend of Omnia 2.0 and Pricemonitor. It is used to manage products, offers, contracts and more.
Use this operation to provide external offers for your products to our system. This operation to add offers in bulk can be used instead of the monitoring by our system of domains for external offers.
This operation needs the internal product ids in our system. See how to determine internal product ids.
Here is an example of a JSON body to provide one offer for one product via API.
[{
"productId": "67784570",
"creationDate": "2024-06-11T00:15:07.099Z",
"domain": "google.de",
"offers": [{
"vendorName": "amazon.de",
"vendorDomainId": 1,
"url": "https://www.amazon.de/-/en/dp/013142467X/",
"price": 58.84,
"deliveryCosts": 9.95,
"currency": "EUR",
"id": "636354d0-c865-4c56-84b3-bd9172e826aa",
"productName": "Test item",
"attributes": [{
"key": "size",
"value": "L"
}],
"maxDeliveryHours": 48,
"minDeliveryHours": 12,
"retrievalDate": "2024-06-11T10:50:45.659Z",
"availability": true
}]
}]Use this operation to get all offers for a contract. It's a paginated endpoint, so you have to scroll through all offers.
It's important that you define a timerange (by providing startDate and endDate parameters) in order to guarantee a stable pagination.
This endpoint returns the most recent offers per product and domain: This means that offers from older monitoring runs within the provided timerange are ignored.
For continuously getting market data we recommend the following usage pattern:
Get the offers for the last 15 minutes with a time offset of 15 minutes.
| Runtime Timestamp | startDate | endDate |
|---|---|---|
| 12:00 | 11:30 | 11:45 |
| 12:15 | 11:45 | 12:00 |
| 12:30 | 12:00 | 12:15 |
| … |
Note: The time offset is important since offers are not immediately visible via the API. Sometimes there is a slight delay in offer storing.
curl -i -X GET \
-u <username>:<password> \
'https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/offers?endDate=2019-08-24T14%3A15%3A22Z&includeTags=true&limit=1000&start=0&startDate=2019-08-24T14%3A15%3A22Z'A list of products with their corresponding offers.
The product information.
Additional imported information as key-value pairs about this product.
The minimum price that Omnia 2.0 can recommend for the product. Omnia 2.0 won't recommend any price below this boundary.
Your ID of the product. This field allows to link products in Omnia 2.0 to products in your system.
The maximum price that Omnia 2.0 can recommend for the product. Omnia 2.0 won't recommend any price above this boundary.
The list of offers for the corresponding product.
The position of the offer on the domain when sorted by total price.
The additional charges for delivering the product to the customer's location (shipping costs).
Optional maximum time, in hours, it takes for the product to be delivered to the customer.
The direct link to the product page on the domain where this offer can be found.
An identifier of the vendor on the domain. Identifiers are available for certain domains only.
Optional minimum time, in hours, it takes for the product to be delivered to the customer.
The position of the offer on the domain when sorted by unit price.
An optional flag indicating whether the product is currently in stock and available for purchase.
A list of additional offer details.
The display name of the shop which sells the product. In some cases (e.g. marketplaces) with some additional information about the seller: e.g. Amazon NL - Sold By Amazon NL
Optional timestamp based on ISO 8601 format, indicating when this offer was fetched from the domain.
An optional timestamp in ISO 8601 format indicating when this offer was stored in Omnia 2.0. This is not the timestamp when the offer was fetched from the domain; for that, use retrievalDate.
The currency in which the price and delivery costs are expressed. Provided values are ISO 4217 currency codes like "EUR".
{ "data": [ { … } ] }
The request body specifies which offers will be searched for.
Warning: It's highly recommended to not use this endpoint since it is error-prone due to complex query structure! Supported are queries with three different types of filters:
left side being a StringValueProvider with the attributeName value "productId"right side being a StringConstantValueProvider with the value being the actual pricemonitor product ID to filter offers forcomparison being a StringEqualityleft side being a NumberValueProvider with the attributeName value "ignoredBy"right side being a NumberConstantValueProvider with the value being the numeric contract id to filter offers forcomparison being a NumberEqualityleft side being a StringValueProvider with the attributeName value "reseller_name"right side being a StringConstantValueProvider with the value being the actual vendor name to filter offers forcomparison being a StringEqualityNote: This endpoint will only return the newest offers for each product for a given time range.
This is a placeholder for filter expressions. They are using advanced features and are not covered by openapi. If you need to use filter expressions please contract us.
curl -i -X POST \
-u <username>:<password> \
https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/offers/query \
-H 'Content-Type: application/json' \
-d '{
"filter": {},
"pagination": {
"limit": 100,
"start": 0
},
"range": {
"end": "2018-04-06T13:46:13Z",
"start": "2018-04-04T13:46:13Z"
},
"sort": {
"metric": "TotalPrice",
"order": "asc"
}
}'Returns either an Error or a list of ApiOffers matching the given filter.
The position of the offer on the domain when sorted by total price.
The additional charges for delivering the product to the customer's location (shipping costs).
Optional maximum time, in hours, it takes for the product to be delivered to the customer.
The direct link to the product page on the domain where this offer can be found.
An identifier of the vendor on the domain. Identifiers are available for certain domains only.
Optional minimum time, in hours, it takes for the product to be delivered to the customer.
The position of the offer on the domain when sorted by unit price.
An optional flag indicating whether the product is currently in stock and available for purchase.
A list of additional offer details.
The display name of the shop which sells the product. In some cases (e.g. marketplaces) with some additional information about the seller: e.g. Amazon NL - Sold By Amazon NL
Optional timestamp based on ISO 8601 format, indicating when this offer was fetched from the domain.
An optional timestamp in ISO 8601 format indicating when this offer was stored in Omnia 2.0. This is not the timestamp when the offer was fetched from the domain; for that, use retrievalDate.
The currency in which the price and delivery costs are expressed. Provided values are ISO 4217 currency codes like "EUR".
{ "data": [ { … } ] }
The request body may include an optional products query. If omitted, all products are queried. Currently, product queries can be performed on two attributes:
Pagination is supported with a maximum limit of 10,000. For optimized performance:
Pagination operates based on the provided products query. This is particularly useful when querying a set of customerProductId's. For chunked requests over a set of ids, it's straightforward to specify up to 10,000 customerProductId's in the query with pagination set at start: 0, limit: 10,000. The allowed query pattern is structured as follows:
"pagination": {
"start": ${start},
"limit": ${limit}
},
"range": {
"start": ${start},
"end": ${end}
},
"filter": {
"oneOf": {
"field": "customerProductId",
"values": [${customerProductIds as a list of strings}]
}
}
} ```Specifies the pagination details such as the start index and the number of records to fetch (limit). At maximum it's allowed to query 10,000 records.
Defines the time range for which offer statistics are queried. Note: The maximum time span between the start and end should not exceed 48 hours.
The starting point of the time range, represented as a timestamp in ISO 8601 format (e.g., "2023-10-19T13:45:30Z") in UTC.
curl -i -X POST \
-u <username>:<password> \
https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3.1/vendor/contracts/qbcxvb/offers/stats/query \
-H 'Content-Type: application/json' \
-d '{
"pagination": {
"start": 0,
"limit": 10
},
"range": {
"start": "2023-10-17T08:00:00Z",
"end": "2023-10-19T08:00:00Z"
},
"filter": {
"oneOf": {
"field": "customerProductId",
"values": [
"1",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9",
"10"
]
}
}
}'Returns a list of offer statistics per product. When a product has no market data then no offer statistics are returned for that product.
The aggregated offer price statistics for the product.
Offer statistics considering the unit price.
Offer statistics considering the unit price plus delivery costs.
A list of offer statistics per domain. Domains without competitor offers are not included in the list.
This field specifies the domain where the competitor offers are sourced from. It's a string representing the domain name, such as "google.de".
{ "data": [ { … } ] }
This endpoint can be used to provide external offers to Pricemonitor. It's a bulk endpoint which accepts an array of individual POST offers requests each based on a "snapshot" - a unique combination of product, domain, and timestamp for a list of offers. Please note the following consistency checks performed before offers are stored:
List of individual POST offers requests which should be added in bulk.
ISO 8601 timestamp when the offers have been gathered. This timestamp needs to be more recent compared to already existing offers. Otherwise, the offers will be rejected.
Non-empty list of offers.
The additional charges for delivering the product to the customer's location.
The direct link to the product page on the domain where this offer can be found.
An optional flag indicating whether the product is currently in stock and available for purchase.
A list of additional offer details.
Optional timestamp based on ISO 8601 when this offer information was last fetched from the domain.
A unique identifier for the offer. It's crucial that it's unique across all offers independent of the timestamp. If you don't have a unique identifier then please use a UUID.
The currency in which the price and delivery costs are expressed. Allowed values are ISO 4217 currency codes like "EUR".
Optional minimum time, in hours, it takes for the product to be delivered to the customer.
curl -i -X POST \
-u <username>:<password> \
https://api-docs.omniaretail.dev/_mock/api/omnia/api/2/v/contracts/qbcxvb/offers \
-H 'Content-Type: application/json' \
-d '[
{
"productId": "string",
"creationDate": "2019-08-24T14:15:22Z",
"domain": "string",
"offers": [
{
"deliveryCosts": 0,
"url": "string",
"vendorDomainId": "string",
"price": 0,
"availability": true,
"attributes": [
{
"key": "string",
"value": "string"
}
],
"vendorName": "string",
"retrievalDate": "2019-08-24T14:15:22Z",
"id": "string",
"productName": "string",
"currency": "string",
"minDeliveryHours": 0,
"maxDeliveryHours": 0
}
]
}
]'The server understood and processed the request. Offers were processed, but not necessarily stored successfully. The 'data' field in the response body contains a detailed report of the operation outcome for each individual POST offers requests. Each item in the 'data' array is either a 'data' object with value true (indicating successful storage), or an ApiErrorResponse (indicating a storage failure).
{ "data": [ { … }, { … } ] }