BETA Product Intelligence API
The Hello Retail Product Intelligence API, which is in its Beta phase, employs cutting-edge artificial intelligence technology to offer an extensive analysis and insights about your product catalog. These valuable insights can significantly influence business decisions such as which products to retain in the inventory and when and how to distribute marketing resources. The Product Intelligence API goes beyond the traditional methods, using AI to extrapolate and understand potential trends and demand, thereby augmenting decision-making with data-driven insights.
The Graph API offers an analytical function that accepts specific product details - the title, description, and an image - and returns comprehensive data insights about:
- Product Lifetime Value
- Recurring nature of the product and its timeline
- Typical discount percentages at which the product is sold
- The typical time of day when the product is purchased
This analytical operation utilizes a clustering technique, which aggregates similar products to the one submitted. Consequently, the results you receive will represent not just the single product you have submitted but a group of products bearing comparable characteristics. This method significantly boosts the data pool, enabling more accurate results.
Please be aware that while the model is based on a substantial dataset, it may not generate insights for every product you submit. This limitation is due to the varying data quantity and quality available for different products. In cases where sufficient data is lacking to deliver an accurate response to a product query, our system opts to send an empty response instead of potentially inaccurate data, thereby upholding the accuracy of the API.
We are continuously updating and improving the model.
Accessing and Authenticating GraphQL API
The data is made availabel in a GraphQL API that is available from the URL:
https://core.helloretail.com/pi/graphql
To interact with the API, you will need to authenticate. Both methods requires a Hello Retail account. If you don't yet have an account, you can create a new one here. There are two primary mechanisms for authentication:
-
User Session Authentication: If you are already logged into my.helloretail.com and try to access the API in your browser, you will be automatically authenticated. This method is primarily useful for testing.
-
API-key Authentication: For robust and efficient integration, especially when you need to integrate the API into your systems, it's recommended to use an API key. You can generate an API key from the 'API Keys' section on my.helloretail.com. Once you have the API key, you can supply it to the API by appending it as a query string parameter
apiKeyto the URL. The URL will then look something like this:https://core.helloretail.com/pi/graphql?apiKey=XXXXXXXXX
Usage
The GraphQL API exposes a single query, closestProduct that uses a product title, description and image to find various information about that product. Detailed documentation of the usage and the returned information can be found in the by visiting the graphql URL in a browser. You need to be logged in to my.helloretail.com to be able to access it, or alternatively provide the API key as mentioned above.
To fetch information about a specific product you could send this GraphQL query
query {
closestProduct(
title: "FILA Sevaro",
desc: "The Fila Sevaro from Fila is made in a stylish design with a ventilated synthetic leather upper for maximum breathability and comfort. The outsole is made of durable rubber, which provides excellent grip and comfort for your feet. The classic lacing system ensures a secure and customizable fit, while the good cushioning provides unbeatable support for long days",
imageUrl: "https://shop.example.com/fila_sevaro.jpg") {
product {
productLifetimeValue
recurrenceDataWeekly {
week
probability
}
recurrenceDataMonthly {
month
probability
}
discountData {
percentageRangeFrom
percentageRangeTo
probability
}
purchaseTimeOfDayData {
hour
probability
}
purchaseDayOfWeekData {
weekday
probability
}
}
}
}
Tip: Try copying the above query to the graphql tester, modify the product information to be one of your own products, and execute the query.
This will return a result like the following. The found information is
recurrenceDataMonthly: List of data points describing the probability of a repurchase happening a certain number of months after the initial purchase, if a repurchase happens at allrecurrenceDataWeekly: List of data points describing the probability of a repurchase happening a certain number of weeks after the initial purchase, if a repurchase happens at alldiscountData: List of data points describing the probability of a purchase happening when the product has a certain discount. The data is split into ranges of discount percentagesproductLifetimeValue: The expected further income that can be expected from customers buying this productpurchaseTimeOfDayData: List of data points describing the probability of the product being bought on a specific hour of the day
{
"data": {
"closestProduct": {
"product": {
"productLifetimeValue": 57,
"recurrenceDataWeekly": [
{
"week": 1,
"probability": 0.2
},
{
"week": 2,
"probability": 0.25
},
{
"week": 3,
"probability": 0.15
},
{
"week": 4,
"probability": 0.1
},
{
"week": 12,
"probability": 0.05
},
{
"week": 22,
"probability": 0.05
},
{
"week": 23,
"probability": 0.05
},
{
"week": 33,
"probability": 0.05
},
{
"week": 41,
"probability": 0.05
},
{
"week": 48,
"probability": 0.05
}
],
"recurrenceDataMonthly": [
{
"month": 1,
"probability": 0.7
},
{
"month": 3,
"probability": 0.05
},
{
"month": 6,
"probability": 0.1
},
{
"month": 8,
"probability": 0.05
},
{
"month": 10,
"probability": 0.05
},
{
"month": 12,
"probability": 0.05
}
],
"discountData": [
{
"percentageRangeFrom": 0,
"percentageRangeTo": 0,
"probability": 0.12471131639722864
},
{
"percentageRangeFrom": 1,
"percentageRangeTo": 10,
"probability": 0.03926096997690531
},
{
"percentageRangeFrom": 11,
"percentageRangeTo": 20,
"probability": 0.4110854503464203
},
{
"percentageRangeFrom": 21,
"percentageRangeTo": 30,
"probability": 0.20092378752886836
},
{
"percentageRangeFrom": 31,
"percentageRangeTo": 40,
"probability": 0.16628175519630484
},
{
"percentageRangeFrom": 41,
"percentageRangeTo": 50,
"probability": 0.03695150115473441
},
{
"percentageRangeFrom": 51,
"percentageRangeTo": 60,
"probability": 0.020785219399538105
}
],
"purchaseTimeOfDayData": [
{
"hour": 0,
"probability": 0.009237875288683603
},
{
"hour": 1,
"probability": 0
},
{
"hour": 2,
"probability": 0
},
{
"hour": 3,
"probability": 0.0023094688221709007
},
{
"hour": 4,
"probability": 0.006928406466512702
},
{
"hour": 5,
"probability": 0.025404157043879907
},
{
"hour": 6,
"probability": 0.03926096997690531
},
{
"hour": 7,
"probability": 0.03002309468822171
},
{
"hour": 8,
"probability": 0.06235565819861432
},
{
"hour": 9,
"probability": 0.03926096997690531
},
{
"hour": 10,
"probability": 0.06004618937644342
},
{
"hour": 11,
"probability": 0.06004618937644342
},
{
"hour": 12,
"probability": 0.04387990762124711
},
{
"hour": 13,
"probability": 0.04157043879907621
},
{
"hour": 14,
"probability": 0.050808314087759814
},
{
"hour": 15,
"probability": 0.057736720554272515
},
{
"hour": 16,
"probability": 0.09930715935334873
},
{
"hour": 17,
"probability": 0.06235565819861432
},
{
"hour": 18,
"probability": 0.06004618937644342
},
{
"hour": 19,
"probability": 0.09468822170900693
},
{
"hour": 20,
"probability": 0.06697459584295612
},
{
"hour": 21,
"probability": 0.04849884526558892
},
{
"hour": 22,
"probability": 0.02771362586605081
},
{
"hour": 23,
"probability": 0.011547344110854504
}
],
"purchaseDayOfWeekData": [
{
"weekday": 1,
"probability": 0.16859122401847576
},
{
"weekday": 2,
"probability": 0.15011547344110854
},
{
"weekday": 3,
"probability": 0.11085450346420324
},
{
"weekday": 4,
"probability": 0.11316397228637413
},
{
"weekday": 5,
"probability": 0.12702078521939955
},
{
"weekday": 6,
"probability": 0.12471131639722864
},
{
"weekday": 7,
"probability": 0.20554272517321015
}
]
}
}
}
}
Example request using javascript
The example query from above can also be sent using the JavaScript fetch API:
const query = `query {
closestProduct(
title: "FILA Sevaro",
desc: "The Fila Sevaro from Fila is made in a stylish design with a ventilated synthetic leather upper for maximum breathability and comfort. The outsole is made of durable rubber, which provides excellent grip and comfort for your feet. The classic lacing system ensures a secure and customizable fit, while the good cushioning provides unbeatable support for long days",
imageUrl: "https://shop.example.com/fila_sevaro.jpg") {
product {
productLifetimeValue
recurrenceDataWeekly {
week
probability
}
recurrenceDataMonthly {
month
probability
}
discountData {
percentageRangeFrom
percentageRangeTo
probability
}
purchaseTimeOfDayData {
hour
probability
}
purchaseDayOfWeekData {
weekday
probability
}
}
}
}`;
const response = await fetch("https://core.helloretail.com/pi/graphql?apiKey=XXX", {
"headers": {
"Content-Type": "application/json"
},
"body": JSON.stringify({query}),
"method": "POST"
});
console.log(await response.json());
Considering the data retrieval process from the API might be slower than desired, we advise implementing periodic querying of the products and storing it in a local database. This strategy ensures quick and efficient data access, improving overall performance.