pixlinQ searchimage API

Overview

The pixlinQ searchimage API allows developers to integrate visual search functionality into their applications using an API key and database of images they have created with the pixlinQ CMS. Below you will find information on how to use the pixlinQ searchimage API.

Getting Started

Before using the pixlinQ searchimage API, you will first need a pixlinQ CMS account and follow steps below:

• Project: Creating a project is simple. Visit the Projects page and click “Create Project”.
• Visuals: Adding Visuals to the project can be done by going to the Visuals page, and clicking "Create Visual". Select the newly created project, and fill in the forms.
• Obtain API Key: Once the project is set up, you may obtain the API Key by visiting the Projects page, and clicking the Title of the project. A pop-up will show various information about the project, including the API key.

Using The searchimage API

The API uses HTTP post requests with the Content-Type set to “multipart/form-data”.
Below you will find:

• Specs for the API, including the URL and Parameters to be passed
• Example request using CURL
• Example JSON responses

API URL

http://api.pixlinq.com/v1/searchimage

Required Parameters

    api_key (text)
      Your API key for your project.  This is created automatically when a project is created. See the
      Getting Started section on obtaining the key.

    image_file (file)
      The image file.  Supported formats: jpeg, png, bmp, gif.  Transparent PNGs and Gifs do not work well.

    device_id (text)
      A unique identifier of the device or email.  This is used for logging and statistics in identifying
      unique users.
    

Optional Parameters

    geoloc(text)
      Geolocation: Coma separated latitude and longitude
      Example for NYC: 40.715, -74.005

    timestamp(text)
      Local user POSIX time in seconds - Used for Targeted Results with specified time range.
      Example: 1315378833 (for 2011-09-07 07:00:33)
    

Error Severity Levels

    warning
      Invalid input of optional parameters.  The request has been processed normally.

    error
      Some internal errors had occured.  Some partial results can be returned.

    fatal
      The request could not be processed.  Missing required parameters, or invalid required parameters.
    

Example Request Using CURL

    
      curl -F "api_key=API_KEY" -F "image_file=@image.jpg;type=image/jpg" \\
      -F "device_id=cURL" http://api.pixlinq.com/v1/searchimage
    
    

Response Example for a Match

{
  "matches": [
    {
      "score": 0.34,
      "title": "LTU",
      "sourcename": null,
      "projectid": "81ee45ce4c421c022f2c4b3e2fe7f148",
      "source": null,
      "visualid": "OBJECT_0003_1305842774",
      "url": "http://www.ltutech.com/ ",
      "others": {},
      "message": "LTU technologies"
    }
  ],
  "sessionid": "DEVICEID/2011/11/11/11/11/11",
  "errors": [],
  "searchtime": 0.51
}
    

Error Response for Missing Required Parameters

{
  "matches": [],
  "sessionid": null,
  "errors": [
    {
      "msg": "Missing mandatory parameter(s): ['device_id', 'image_file', 'api_key']",
      "severity": "fatal"
    }
  ]
}

    

Error Response for Wrong API Key

{
  "matches": [],
  "sessionid": "DEVICEID/2011/11/11/11/11/11",
  "errors": [
    {
      "msg": "API key not recognized: 'abc'",
      "severity": "fatal"
    }
  ]
}

    

Error Response for Invalid Image/File

{
  "matches": [],
  "sessionid": "DEVICEID/2011/11/11/11/11/11",
  "errors": [
    {
      "msg": "Image search failed (File is not an image. / LTU SOAP server error /
        Can't compute DNA (the file is not an image))",
      "severity": "fatal"
    }
  ],
  "searchtime": 0.059
}