API Reference Guide
Introduction
General remarks, endpoints
SOAP or REST API interface?
Data structure
Typical Price2Spy API usage scenarios
Price2Spy request authentication
List of operations
Introduction
Introduction
Price2Spy API represents an interface between 3rd party software (referred as ‘external application’) and Price2Spy. It enables accessing and managing Price2Spy data programmatically, without any need for human interaction.General remarks, endpoints
General remarks, endpoints
- Environments
- Production environment (price checks regularly done)
- SOAP interface
- WSDL – https://api.price2spy.com/soap?wsdl
- REST interface
- REST API Endpoint: https://api.price2spy.com/rest/v1
- Documentation and testing (Swagger) URL:
https://api.price2spy.com/rest/swagger-ui.html#/
- Price2Spy GUI – https://spy.price2spy.com/price2spy
- Client ID and Client Secret – please contact support@price2spy.com
- SOAP interface
- Development environment
- The development environment is there for you to test if the logic of your app works as expected
- Price2Spy does not have a separate development environment for you to use. However, we can open a TEST Price2Spy account for you, which will be used to test your app logic
- If you need such TEST account, please contact support@price2spy.com
- That means that API URL / endpoints will remain the same, it’s just that API KEY will be different from the PRODUCTION one (the TEST API KEY will be provided by your account manager)
- TEST account will by default be empty, please let us know if you’d like some products / URLs copied from your PRODUCTION account
- Production environment (price checks regularly done)
- Timestamps
- REST interface: both response and request use UTC
- SOAP interface: CET is used for requests and responses. The responses will contain the exact timezone
- All prices/currencies are as captured on-site (setting ‘show all prices in my currency’ not taken into account)
SOAP or REST API interface?
SOAP or REST API interface?
Starting from version 2.51 – Price2Spy offers both SOAP and REST interfaces. If you’re using SOAP – please keep in mind that some SOAP clients need to know in which technology was the SOAP server built. In our case, that is Apache CXF JAX-WS
This document covers common Price2Spy topics, no matter if you use SOAP or REST API interface.
However, the documentation on details of implementation and examples are split
- SOAP – the documentation and examples are extracted in following document https://www.price2spy.com/en/api/documentation/soap-api.html
- REST – the documentation is provided in standard Swagger format: https://api.price2spy.com/rest/swagger-ui.html#/
- REST Authentication is performed by adding Authorization header to your REST API requests. The contents of the header is Basic
Example: Authorization = Basic YmI1MTkzYTdkMzM4YTZmOTEwZmZiYjAxZjhmMzA2YTZlMjJjNDk3Ng==
- REST Authentication is performed by adding Authorization header to your REST API requests. The contents of the header is Basic
Data structure
Data structure
Price2Spy data structure backbone consists of 3 objects.- Product – usually represents an item sold on an online store. Contains one or more URLs from different websites.
- URL – concrete page where the above product can be found on given website. Contains one or more measurements (price checks).
- Measurement (or price point) – concrete result of a price check performed by Price2Spy. A price point gets stored in Price2Spy only if it’s value differs to what was captured in previous price check.
Typical Price2Spy API usage scenarios
Typical Price2Spy API usage scenarios
In this chapter, we will try to cover typical scenarios on how your application (referenced as ‘external application’) can interface Price2Spy.A) Full integration: External app. supplies Products and URLs; Price2Spy supplies pricing data
In this scenario Products and their corresponding URLs are defined in external application, which periodically (usually via a scheduled process) feeds these products and URLs to Price2Spy – using insertProduct() and insertUrl() operations. In this scenario it is essential that the external application records productId and urlId returned by Price2Spy because that will ensure proper object mapping. It is also highly recommendable to supply productId from the external app as internal_id attribute of the insertProduct() operation. Once Products and URLs get defined in Price2Spy, it will start monitoring those for price changes. External application can retrieve up-to-date pricing information by using getCurrentPricingData() operation. External application can store pricing data in its own tables (or other data structures) and make logical decisions based on this data (for example – adjusting own prices based on pricing data supplied by Price2Spy and on available price margins). Again, it is highly advisable to schedule getCurrentPricingData() as a background process in an external application (for example: 1-6 times a day) B) Partial integration: Products and URLs manually entered in Price2Spy, Price2Spy feeds pricing data to external app.
In this scenario Products and their corresponding URLs are added manually to Price2Spy (using Price2Spy web interface). On the other hand, external application periodically queries Price2Spy for data changes (getCurrentPricingData() operation). Since getCurrentPricingData() returns complete Product and URL objects, it can be used to reconstruct these objects in external application (although they had not been originally entered there) C) Partial integration: External application supplies Products and URLs; Price2Spy price change alerts used
This scenario is used by one of our recent clients: they have a process that crawls competitor sites and matches the products. If there is a product that is newly matched, its URL gets communicated to Price2Spy (insertUrl() operation). However, this customer does not keep pricing data in his own applications, therefore he does not need to receive the pricing feed via getCurrentPricingData() operation – they fully rely on Price2Spy’s email alert mechanism.Price2Spy request authentication
Price2Spy request authentication
Request for each Price2Spy operation consists of 2 parts
- Request-specific element (example for insert operations: insert)
- apiKey – used to authenticate you to Price2Spy API. Can be found when you log in to Price2Spy – Settings
Possible authentication-related faults (applicable to all operations)
- apiKeyWrong – check if you have supplied correct API key
- apiAccessNotAllowed – please check if this is enabled in your Settings
List of operations
List of operations
- Managing Price2Spy data (insert / update / delete operations)
- insertProduct
- updateProduct
- deleteProduct
- insertUrl
- updateUrl
- deleteUrl
- insertCategory
- updateCategory
- deleteCategory
- insertBrand
- updateBrand
- deleteBrand
- insertSupplier
- updateSupplier
- deleteSupplier
- insertMetadata1
- updateMetadata1
- deleteMetadata1
- insertMetadata2
- updateMetadata2
- deleteMetadata2
- insertMetadata3
- updateMetadata3
- deleteMetadata3
- Retrieving Price2Spy data (‘get’ operations)
- getProducts-get products for given search criteria
- getUrls – get URLs for given product(s)
- getMeasurements – get price checks (measurements) for given URL
- getCurrentPricingData – get all Price2Spy data for products matching given search criteria
- getBrands – get all brands
- getCategories – get all categories
- getSuppliers – get all suppliers
- getMetadata1 – get all metadata1 fields
- getMetadata2 – get all metadata2 fields
- getMetadata3 – get all metadata3 fields