Picsure API

Updated at 06 August 2018

The Picsure API offers a simple interface for uploading an image and fetching product informations about items recognized on that image.

This document describes the usage of the Picsure-API.

Prerequisites

All examples given in this document uses the curl command line tools.

A WebHook can be used for catching the notifications sent from the Picsure service. RequestBin is a good starting point for testing purpose:

You can easily create an endpoint there and inspect the data posted by the Picsure service.

Installation

curl - should be already available in your shell. Or download it here.

Usage

The Picsure API for external clients exposes one endpoint for uploading the image. The following lookup for the image content can then be done by either:

a) lookup after a WebHook notification from the Picsure service
b) lookup with long-polling

  1. Image upload
  2. Optional WebHook notification
  3. Looking up data
  4. Adding image label

1. Image upload

The Picsure API uses the https://api.picsure.ai/1/upload?pingback=some_pingback_url endpoint for posting images to the server.

The ?pingback parameter is optional and only useful for lookups after WebHook notifications.

Authorization to the service is granted by a Bearer {TOKEN}.

The request looks like:

curl -X POST \
  'https://api.picsure.ai/1/upload?pingback=https://requestb.in/y04veyy0' \
  -H 'Authorization: Bearer {TOKEN}' \
  -H 'Content-Type: multipart/form-data' \
  -F upload=@/Users/oroel/Downloads/image.jpeg
  -F 'exif={EXIF_JSON}'

Or, without pingback:

curl -X POST \
  'https://api.picsure.ai/1/upload' \
  -H 'Authorization: Bearer {TOKEN}' \
  -H 'Content-Type: multipart/form-data' \
  -F upload=@/Users/oroel/Downloads/image.jpeg
  -F 'exif={EXIF_JSON}'

Where {TOKEN} has to be replaced by the real token sent to you by Picsure. {EXIF_JSON} is an optional parameter to transmit exif-data separately. This can be necessary because images often loose their EXIF-data by resizing. The Exif-Data has to be in JSON-Format. The upload form element is the only data required by the endpoint.

Only POST and OPTIONS requests are permitted by the API.

The service responds with a token:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "token": "90f11b4a-d6a7-42f4-80f8-7b2bb931a026"
}

2. Optional WebHook notification

When the service has finalized the image recognition it will send out a notifications if a pingback URL parameter was present in the upload URI. The event will be sent via a POST request.

The payload of the posted WebHook simply is:

{
    "token": "90f11b4a-d6a7-42f4-80f8-7b2bb931a026",
}

The header carries HMAC signature:

X-Picsure-Signature: {Some-Signature}

{Some-Signature} is a HMAC with sha1 hash value of the request body. The private key for the sha1 key is handed out to you from Picsure together with the Bearer {TOKEN}.

3. Looking up data

Fetching the data for the uploaded image is done by GET request with the token returned in the image POST. If the pingback WebHook is not used the lookup will keep the connection open, until the data have been processed.

Please note, the version of the endpoint here is ‘2’, since the previously used version ‘1’ didn’t support long-polling.

curl -X GET \
  https://api.picsure.ai/2/lookup/90f11b4a-d6a7-42f4-80f8-7b2bb931a026 \
  -H 'authorization: Bearer {TOKEN}' \
  -H 'accept-language: en'

The accept-language header is used for localisation and language of the response. It accepts language and locale in the form de, de-CH. I.e. it is a combination of ISO 639 and ISO 3166-1 codes as described in paragraph 14.4 of rfc2616.

A response may look like the following:

{
  "object_recognition": [
    {
        "label": "Camera",
        "category": "camera",
        "subcategories": [],
        "price_indication": {
            "CHF": 560
        }
    },
    {
        "label": "Nikon D500",
        "category": "camera",
        "subcategories": [
            "nikon-d500",
            "nikon"
        ],
        "price_indication": {
            "CHF": 2393
        }
    },
    {
        "label": "Nikon D5",
        "category": "camera",
        "subcategories": [
            "nikon-d5",
            "nikon"
        ],
        "price_indication": {
            "CHF": 7639
        }
    },
    {
        "label": "DSLR Camera",
        "category": "camera",
        "subcategories": [
            "dslr-camera"
        ],
        "price_indication": {
            "CHF": 664
        }
    }
  ],
 "fraud_detection": {
        "exif_data_found": true,
        "imagehash": {
            "hash_value": "9d59e6b6c80981f6",
            "hash_duplicate_found": true,
            "duplicates": [
                {
                    "agency": "Company A",
                    "upload_date": "2018-07-25T08:55:23+00:00",
                    "hash_value": "9d59e6b6c80981f6"
                }
            ]
        },
        "location": {
            "lat": 43.467081666663894,
            "lng": 11.884538333330555
        },
        "gps_date": "2008-10-23T14:36:47+00:00",
        "create_date": "2008-10-22T16:38:20+00:00",
        "modify_date": "2008-11-01T21:15:08+00:00",
        "is_modified": true,
        "found_in_web": false,
        "urls": [],
        "days_photo_taken": 3574,
        "ela_image": null,
        "upload_date": "2018-08-06T13:02:19+00:00",
        "ela": {
            "image_url": "https://images.picsure.ai/media/uploads/image_V8DVs8d_ela.jpg",
            "max_difference": 51
        },
        "address": [
            "Via Madonna Laura, 10, 52100 Arezzo AR, Italy",
            "Via Madonna Laura, 52100 Arezzo AR, Italy"
        ],
        "truthfulness": 0
    }
}

Object recognition

The JSON reponse is a an object with an object_recognition property, which is a list of items falling under one category.

The items attributes are:

The general category is described by the entry with an empty subcategories list.

The list can have up to four items. And it can be empty, if the items found on the uploaded image doesn’t match with the catgegories-list for the customer. For example: the response above would be empty, if the customer is only interested in cat detection.

Fraud detection

The ‘fraud_detection’ property contains results of all frauddetection-services.

The fraud detection attributes are:

Adding image label

The Picsure API allows to add label data to the uploaded image. This is done by a POSTrequest:

curl -X POST \
  https://api.picsure.ai/2/label/90f11b4a-d6a7-42f4-80f8-7b2bb931a026 \
  -H 'Authorization: Bearer {TOKEN}' \
  -H 'Accept-Language: en-US' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "test label"
}'

The label data needs to be posted in the body of the HTTP request as a JSON structure:

{
  "label": "some label text"
}

The language of the posted label data is extracted from the Accept-Language header field.

The server will respond with a 201 CREATED response when the new label has been added to the image.