NAV Navbar
shell
  • Introduction
  • Authentication
  • Autocrop
  • Food
  • Similar Images
  • Product Review
  • Errors
  • Introduction

    Welcome to the Turing Analytics API.

    We have provided code examples in Shell! You can view code examples in the dark area to the right. If you have any questions, you can write us at mail@turingiq.com

    Authentication

    To authorize, use this code:

    # With shell, you can just pass the correct header with each request
    curl "api_endpoint_here"
      -H "Authorization: Bearer your_api_key"
    

    Make sure to replace your_api_key with your API key.

    Turing uses API keys to allow access to the API. You can register a new Turing API key at our developer portal.

    Turing expects for the API key to be included in all API requests to the server in a header that looks like the following:

    Authorization: Bearer your_api_key

    Alternatively, you can also provide API key in access_token URL parameter.

    Autocrop

    Get autocrop boxes for image

    curl "https://api.turingiq.com/v1/autocrop?access_token=your_api_key&url=https://example.com/image.png"
    

    The above command returns JSON structured like this.:

    {
      "boxes": [
        [0, 20, 327, 140],
        [67, 30, 545, 439]
      ],
      "url": "https://example.com/image.png"
    }
    

    This endpoint automatically detects objects in image and gives bounding boxes around them as response. The bounding box format is [xmin, ymin, xmax, ymax]

    HTTPS Request

    GET https://api.turingiq.com/v1/autocrop

    Parameters

    Parameter Required Description
    url true URL of image for which the bounding boxes has to be found
    access_token true API access token

    Food

    Identify whether the photo contains food

    curl "https://api.turingiq.com/v1/food?access_token=your_api_key&url=https://example.com/image.png"
    

    The above command returns JSON structured like this.:

    {
      "food": true
    }
    

    This endpoint detects whether the uploaded image has food item in in and returns boolean value.

    HTTPS Request

    GET https://api.turingiq.com/v1/food

    Parameters

    Parameter Required Description
    url true URL of image for which the bounding boxes has to be found
    access_token true API access token

    Similar Images

    Get similar images

    curl "https://api.turingiq.com/v1/similar/2"
      -H "Authorization: Bearer your_api_key"
    

    The above command returns JSON structured like this:

    {
      "similar": [
      {
        "id": "1"
        "url": "https://example.com/image.png",
        "similarity": 0.95,
        "product_name": "Product 1"
      }, 
      {
        "id": "3"
        "url": "https://example.com/other_image.png",
        "similarity": 0.93,
        "product_name": "Product 3"
      }]
    }
    

    This endpoint retrieves similar images to an image already stored in our index. The returned array is sorted in decending order of similarity score.

    HTTPS Request

    GET https://api.turingiq.com/v1/similar/<ID>

    URL Parameters

    Parameter Required Description
    url true URL of image for which visually similar images are to be found
    filter1 false Filter field 1 - pass this to retrieve subset of results. Pass comma saperated values to apply multiple filters. E.g. filter1=green,blue will select all images with filter1 values green and blue.
    filter2 false Filter field 2 - pass this to retrieve subset of results based on filter2 value
    filter3 false Filter field 3 - pass this to retrieve subset of results based on filter3 value
    curl "https://api.turingiq.com/v1/similar/search"
      -X POST
      -H "Authorization: Bearer your_api_key"
      -d "url=https://example.com/image.png"
      -d "crop=7,20,353,476"
    

    The above command returns JSON structured like this:

    {
      "similar": [
      {
        "id": "1"
        "url": "https://example.com/image.png",
        "similarity": 0.999,
        "product_name": "Product 1"
      }, 
      {
        "id": "2"
        "url": "https://example.com/similar_image.png",
        "similarity": 0.95,
        "product_name": "Product 2"
      },
      {
        "id": "3"
        "url": "https://example.com/other_image.png",
        "similarity": 0.93,
        "product_name": "Product 3"
      }]
    }
    

    This endpoint retrieves visually similar images from indexed set. The returned array is sorted in decending order of similarity score.

    You can also supply a crop parameter to crop image on our end and then perform similar search.

    HTTPS Request

    POST https://api.turingiq.com/v1/similar/search

    Parameters

    Parameter Required Description
    url true URL of image for which visually similar images are to be found
    crop false Crop box co-ordinates as comma saperated string xmin,ymin,xmax,ymax
    filter1 false Filter field 1 - pass this to retrieve subset of results. Pass comma saperated values to apply multiple filters. E.g. filter1=green,blue will select all images with filter1 values green and blue.
    filter2 false Filter field 2 - pass this to retrieve subset of results based on filter2 value
    filter3 false Filter field 3 - pass this to retrieve subset of results based on filter3 value

    Add new image to index / Update Index

    curl "https://api.turingiq.com/v1/similar/create"
      -X POST
      -H "Authorization: Bearer your_api_key"
      -d "url=https://example.com/image.png"
      -d "id=2"
      -d "product_name=Product 1"
      -d "filter1=brand_name"
    

    The above command returns JSON structured like this:

    {
      "success": true
    }
    

    This endpoint adds new image to Turing index. The ID of image much be unique across all your indexed images. If ID is already found in index, the data is updated for the image ID.

    HTTPS Request

    POST https://api.turingiq.com/v1/similar/create

    Parameters

    Parameter Required Description
    url true URL of image to be added to index
    id true ID of image. If ID is already found in index, the existing data is updated
    filter1 false Filter field 1 to query on in search requests
    filter2 false Filter field 2 to query on in search requests
    filter3 false Filter field 3 to query on in search requests
    your_field optional false Any other field you want to supply like image_name or product_name

    Delete image from index

    curl "https://api.turingiq.com/v1/similar/2"
      -X DELETE
      -H "Authorization: Bearer your_api_key"
    

    The above command returns JSON structured like this:

    {
      "success": true
    }
    

    This endpoint will delete image from index.

    HTTPS Request

    DELETE https://api.turingiq.com/v1/similar/<ID>

    URL Parameters

    Parameter Required Description
    id true ID of image to be deleted

    Product Review

    Classify product review

    curl "https://api.turingiq.com/v1/classify/review"
      -X POST
      -H "Authorization: Bearer your_api_key"
      -d "reviewId=109092"
      -d "review=This product is useful and as described"
    

    The above command returns JSON structured like this.:

    {
      "reviewId": "109092",
      "review": "This product is useful and as described",
      "sentiment": "positive",
      "status": "approved",
      "context": ["quality","description"],
      "specificityScore": 0.7
    }
    

    This endpoint classifies customer reviews posted on products.

    HTTPS Request

    POST https://api.turingiq.com/v1/classify/review

    Parameters

    Parameter Required Description
    reviewId true Unique ID of review.
    review true Text of the review which needs to be classified
    created false UNIX timestamp of review creation time (recommended). If not used, we will use time of this API call
    productId false ID of product with which review is associated (recommended)
    productName false Name of product with which review is associated (recommended)
    categoryId false ID of category to which the product belongs (recommended)
    categoryName false Name of category to which the product belong (recommended)
    subCatId false ID of sub category to which the product belongs (recommended)
    subCatName false Name of sub category to which the product belongs (recommended)
    merchantId false ID of merchant who sold this product (recommended)
    merchantName false Name of merchant who sold this product (recommended)
    reviewerId false ID of person who posted the product review (recommended)
    reviewerName false Name of person who posted the product review (recommended)
    productRating false Rating scrore given to product with this review (0-5)
    merchantRating false Rating scrore given to merchant with this review (0-5)

    Errors

    API gives all error response in following JSON format:

    {
      "code": "API error code",
      "error": "Error message describing details of error"
    }
    

    The Turing API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request has some problems.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- The resourse is not allowed to be access by this user.
    404 Not Found -- The specified resource could not be found.
    406 Not Acceptable -- You requested a format that isn't json.
    429 Too Many Requests -- You're requesting too fast. The headers will display after how long you should send next request
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.