KPN Image Recognition API

API reference on SwaggerHub

Introduction

The Image Recognition API adds image analysis to your application. Gain insights in images and classify them in any category. Automatically add labels to images and organize your content. You can make images searchable using categorization and filtering. This API is capable of detecting multiple objects.

The image classifier is provided as is, and the images classifications have around 90% accuracy on non-domain specific images. Future versions of the API can offer training on provided images.

Conceptual model

Conceptual model

Definitions

Score

The score that is given by the API should be read as a probability figure that defines how likely it is that the picture provided, is matching the result classification. A score of 0.83726 means that it's little more than 83% likely that the picture provided, contains the associated classification.

API workflow

API workflow

Features and constraints

Features

  • Multiple images can be provided in each request.
  • Fast analysis of the image
  • Many classifications possible for a single image, each provided with a probability weight.

Constraints

  • Only one image per request is allowed.
  • Provided images need to be referenced by URL, so they have to be online.

Getting started

Authentication

To authenticate you'll need to request an access token. Use your API Store app's credentials (Consumer Key and Consumer Secret) to make an authentication request. The authorization service returns a JSON message that contains the access_token field.

Use one of the following 3 options:

cURL

Execute below cURL command to receive an access token. Replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with your app's credentials.

curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

If you are using cURL for Windows, please use the command below instead.

curl -X POST "https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials" -H "content-type: application/x-www-form-urlencoded" -d "client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET"

The authentication service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[xxxxxxx]",
    "api_product_list_json": [
        " xxxxxxx"
    ],
    "organization_name": "kpn",
    "developer_email": "demo123@kpn.com",
    "token_type": "Bearer",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38edxxxxxxxxxxxxxxxx4065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

SwaggerHub

  1. Click on the Authorize button on the top right.
  2. In the form, fill in client_id and client_secret, using your app's credentials.
  3. Click Authorize.

Postman

When using Postman, you will have to import the Swagger file into a Postman collection as follows:

  1. Open the API reference on SwaggerHub.
  2. On the top right, click Export, click Download API and click 'YAML Unresolved'.
  3. In Postman from the menu click File and click Import... Choose the YAML file you downloaded in the previous step. A new collection will be added.
  4. Select Get Access Token from the collection.
  5. Make sure the right environment is selected, corresponding to the API.
  6. Edit the environment variables client_id and client_secret, using your app's credentials.
  7. Check the response code and message.
  8. Press the Send button to get an access token.

Note: Request variables are no longer linked to an environment, but to the collection.

How to...

Recognize a provided image

Let the API recognize your image(s). You will have to provide the images that to be recognized by providing the URL of the images. Make a JSON list of those images using the small example structure below. Change and add your own images and copy your work to be pasted in the Body section of the request.

{
  "data": [
    {
      "ext": "jpg",
      "path": "https://upload.wikimedia.org/wikipedia/commons/0/0e/Atlanta_Zoo_Panda.jpg"
    },
    {
      "ext": "jpg",
      "path": "http://www.babushahi.com/upload/image/Train-Engine_HKM.jpg"
    }
  ]
}

SwaggerHub:

  1. Select POST /classify.
  2. Click Try it out.
  3. Edit the parameters by filling out the Body with the snippet you copied from above.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Select (POST) Classify.
  2. In the Body section of the request, make sure raw is selected and paste the snippet you copied from above.
  3. Click Send.
  4. Check the response code and message.

Result example:

{
  "status": "OK",
  "results": [
    {
      "url": "https://upload.wikimedia.org/wikipedia/commons/0/0e/Atlanta_Zoo_Panda.jpg",
      "result": [
        {
          "score": "0.93182",
          "classification": "giant panda, panda, panda bear, coon bear, Ailuropoda melanoleuca"
        },
        {
          "score": "0.00135",
          "classification": "lesser panda, red panda, panda, bear cat, cat bear, Ailurus fulgens"
        },
        {
          "score": "0.00044",
          "classification": "indri, indris, Indri indri, Indri brevicaudatus"
        },
        {
          "score": "0.00042",
          "classification": "earthstar"
        },
        {
          "score": "0.00032",
          "classification": "ice bear, polar bear, Ursus Maritimus, Thalarctos maritimus"
        }
      ]
    },
    {
      "url": "http://www.babushahi.com/upload/image/Train-Engine_HKM.jpg",
       "result": [
        {
          "score": "0.73778",
          "classification": "electric locomotive"
        },
        {
          "score": "0.16747",
          "classification": "passenger car, coach, carriage"
        },
        {
          "score": "0.04318",
          "classification": "freight car"
        },
        {
          "score": "0.00627",
          "classification": "steam locomotive"
        },
        {
          "score": "0.00037",
          "classification": "viaduct"
        }
      ]
    }
  ]
}

Return codes

Code   Description
200   Success
201   Created
202   Accepted
302   Found. Link in location header
400   Bad request
401   Unauthorized
403   Forbidden
404   Not found
405   Method not allowed
412   Precondition failed
429   Too many requests
500   Internal server error
502   Bad gateway
503   Service unavailable