Skip to main content

Sending an image for analysis via API

  • Updated

To know how to send a receipt via the user interface, click here!

You can use our API on a lot of different combinations or usages. But it all starts with the need of a simple analysis of a receipt.

Through this documentation we will simply send an image and get back analysis extracted from it. It will be the perfect place to also explain all the concepts you could use if you need to scale (going industrial 🏭) your receipt analysis process and / or use our rules validations tools.

Sending an image for analysis

We will cover here the basic workflow with an introduction to the basic concepts

AntarSimpleProcess.png

Preparing the request

  • In order to send a receipt you need to be authenticated on our API, if you did not, please read carefully the How to connect to our API guide before going further
  • You also need to have an image of a receipt on your computer ready to be analyzed. Do not forget to follow our guidelines 📷.
  • In order for you to retrieve the receipt analysis after sending the image, you need to name your receipt. Make sure this name is unique

WARNING
Because nobody reads if it's not in red marked with danger: Make sure the name you choose for the receipt is unique for your account (not necessarily universally).

Making the request

Building the request:

less {path_to_your_file.jpg} | http POST "https://api.kweeri.io/documents?name={your_unique_document_name}&dominantLanguage=fr-FR" 'Authorization: bearer {your_access_token}'

You have to specify a dominant receipt language to get a correct analysis, you can find more informations at the end of this article.

You should get a response like this:

HTTP/1.1 200 OK
{
    "name": "document_identifier", //A reminder of the id you specified (name)
    "uid" : "EDEDEDE-EDEDEDE-EDEDED-EDEDED", //universal unique id generated by our system.
    "status": "WAITING_FOR_PROCESS" //Meaning that your image is in queue for being processed,
    [...]
}

 

WARNING
The answer is instant, but it does not mean the receipt has been analyzed and extracted. The process is an asynchronous task that takes times. Here is an article explaining the time that takes a receipt to get processed.

We do not wait for receipt to be analyzed to launch the HTTP response, because it is a bad practice (security and performance) to let open a connection for a long time.

Status and results

From now, you have to monitor when the data are actually extracted from the receipt.

You can make a request to get the data of this document:

GET https://api.kweeri.io/documents?filter=name:{document_identifier} 'Authorization: bearer {your_access_token}'

 

You can specify numerous ways to retrieve a receipt, not only by its name, and get a list of matching filters.

You should get a response like this:

HTTP/1.1 200 OK
{
    "name": "document_identifier", //A reminder of the id you specified (name)
    "uid" : "EDEDEDE-EDEDEDE-EDEDED-EDEDED", //universal unique id generated by our system.
    "status": "PROCESSING" //Meaning that your image is currently being process
    [...]
}

 

So until you get a status with the value PROCESSED it means that your receipt is not ready yet. When PROCESSED is set you can start interpreting the results, and exploring data extracted from the image.

We are able to push back data to your system when it's ready, just read this guide to make the magic happen.

Finally if you try again the request like 30 sec after we should have finished your analysis:

HTTP/1.1 200 OK
{
    "name": "document_identifier", //A reminder of the id you specified (name)
    "uid" : "EDEDEDE-EDEDEDE-EDEDED-EDEDED", //universal unique id generated by our system.
    "status": "PROCESSED", //The analysis is done, you can browse the data
    "data" : {}, //Extracted data from receipt image
    [...]
}

 

This is the simplest way to send image and get back results.

Browsing your receipts

You will probably send more than one receipt. So we built some routes for browsing and searching through them. You can read the following API documentation to learn more about all possible routes.

Keep in mind that you can only use the /documents/ routes if you do not create any endpoints or campaign.

Endpoint & Campaign

Endpoints and Campaign are two abstractions we have made to fill the needs of our clients who have to deal with a lot of receipts from different sources.

On the previous part of this guide, we sent the receipt directly on the /documents routes, which removes the layer of endpoints / campaigns and makes it easier to use. But it quickly becomes a mess to browse and retrieve receipts without these layers.

You can use the API for many receipts and receipts sources, from mobile app to server. But also for different purposes, from just data extraction to marketing promotion validation. So we have designed some ways to organize and manage your receipts and other features offered by our API.

AntarEndpointProcess.png

Endpoints and Campaigns are ways to organize and put some meta processing to your receipts.

Endpoints

Endpoints are simply anchors to retrieve a set of receipts. They are for you a unique URL under which some receipts coming from a given source are grouped.

For example you receive receipts from a mobile application and you want them to be forwarded to a specific point in your back-end. Then you want to use endpoints.

To upload an image to an Endpoint

You can make a request to get the data of this document:

GET https://api.kweeri.io/endpoints/{endpoint_id}/documents?filter=name:{document_identifier}

See API Documentation for Endpoints here

Campaign

Campaigns are also anchors to retrieve a set of receipts. They differ from Endpoints because they also carry a rules validation logic.

Learn more about Campaign and Promotion here.

See API Documentation for campaign here

Understanding extracted data from a receipt

When you get back analysis from our system, there are numerous fields of data, it can be hard to understand every field. Thankfully we have documented each field on the API Documentation.

WARNING
We encourage you to read it carefully.

A Quick summary of what you can get:

  • Global information about the receipt
    • Sign
    • City
    • Postal Code
    • Address
    • Total Amount
    • Currency
    • Barcode
    • Date & Hour of purchase
    • Number of products
    • Phone of the store
  • On the product part and for each product
    • Raw label (As read on receipt)
    • Short Label (A Cleaner label without extra data)
    • Quantity
    • Price
    • Unit Price
    • Mass
    • Brand
    • Category

Dominant receipt language

The dominant receipt language is used to specify on which language the system should analyze the receipt. Depending on this information, the system will use country specific data to do the analysis like brands, signs or shops.

By this way, a spanish receipt analyzed with dominant language set to fr-FR (french language) will not be correctly analyzed.

Today, we propose 3 different languages :

  • French 🇫🇷 - fr-FR
  • Spanish 🇪🇸 - es-ES
  • Italian 🇮🇹 - it-IT

Comments

0 comments

Please sign in to leave a comment.

Table of content

    Powered by Zendesk