NAV Navbar
cURL Python

Introduction

Welcome to the IMATAG API!

This API is intended for enterprise customers to register on-premises watermarked media and track their usage on the Internet or via PDF analysis.

Authentication

We use token authorization via HTTP header, to provide secure access to your account via our API.

To authorize, use this code:

import requests

# with requests library, you can just pass the correct header with each request
headers = {"Authorization":"Token putyourapitokenhere"}
response = requests.get("api_endpoint_here", headers=headers)
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "Authorization: Token putyourapitokenhere"

Make sure to replace putyourapitokenhere with your API key.

IMATAG uses API keys to allow access to the API. Your API key is available in your account settings on IMATAG

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

Authorization: Token putyourapitokenhere

Request IDs

Each API request has an associated request identifier. You can find this value in the response headers, under X-Request-Id. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

Versioning

The versioning of the API is specified as part of the URI. For instance, in order to use v1 of the API the request URI should begin with /v1 followed by a specific endpoint.

https://imatag.com/api/v1

Pagination

All endpoints which return collections of objects use pagination. All those endpoints return the following attributes in their response:

Attribute Description
count Total number of objects
next url of the next objects in the sequence (null if end is reached)
previous url of the previous objects in the sequence (null at the start)
<attr_name> list of paginated objects (current chunk)

To navigate the collection, you need to iteratively do GET requests at the url provided in the next attribute for each chunk of the collection.

API Playground

If you want to try out our API in a secure playground, without using your own account, you can use our api.demo account, which has limited 10Mb quota on the uploads folder. Only the uploads folder is writable, the other ones are only readable.

To use this account, you'll need to use the authorization token fd8fef6e430595edc3bab691d9a83230f0a56b99.

This account contains CC0-watermarked images that were uploaded and tracked on the Internet via our crawlers for demo purpose (to find similar or watermarked copies). You'll be able to see thoses images & track their detected usage via the API.

tour eiffel paris coucher soleil paris

Status Codes / Errors

Errors returned by the API may have a response body in the following form:

{
    'status_code': <http status code>,
    'code': 'optional_error_code',
    'details': 'either human readable message about the error or a nested structure with more details',
    'errors': 'a list or errors details when multiple errors occurred'
}
{
    'status_code': <http status code>,
    'code': 'optional_error_code',
    'details': 'either human readable message about the error or a nested structure with more details',
    'errors': 'a list or errors details when multiple errors occurred'
}

IMATAG uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with IMATAG's servers.

Status Code Meaning
200 OK -- Everything worked as expected.
201  Created -- A new resource was created.
204  No Content -- The resource was properly deleted - or no content was available to be returned
--- ---
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- You don't have enough permission to access the requested resource.
404 Not Found -- The resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
409 Conflict -- The request could not be completed due to a conflict with the current state of the target resource.
410 Gone -- The requested endpoint has been removed from our servers.
411 Length Required -- The body is empty or the Content-Length is missing in the request headers.
415 Unsupported Media Type -- The content of the request is not in a format supported by the endpoint.
429 Too Many Requests -- You're requesting too many resources! Slow down!
--- ---
500 Internal Server Error -- We had a problem with our server. Try again later.
501 Not Implemented -- The requested endpoint is documented by not yet developped. It will be available in the future.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
504 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

API Endpoints

Below is the list of all available endpoints & their full description: this is API time!

Media

The media endpoint allows you to register and manage your media on IMATAG. The management part is quite standard: you PUT your media somewhere, and you can afterward GET it or DELETE it. What sets us apart is that all media you have added IMATAG is registered which means two things:

The flipside is that any media which has been marked but not registered on IMATAG or which has been deleted won't be searched for anywhere and we won't be able to find it's watermark even from a manual query.

Media are organised in a folder tree structure. There are few constraints on the folder structure/naming:

Media object

This model defines the list of attributes for all objects accessible along the path i.e. folder, image, document, etc.

Argument Description
url The URL of the media
path The path of the media
created The date of creation of the media
type The type of object: folder, image, document
children For folder, the list of objects contained in that folder (paginated)
image For image, the static URL of the watermarked thumbnail preview.

List a folder

import requests

headers = {
    'Authorization': 'Token fd8fef6e430595edc3bab691d9a83230f0a56b99',
}
response = requests.get('https://imatag.com/api/v1/media/api.demo/images', headers=headers)
curl https://imatag.com/api/v1/media/api.demo/images \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

The above command returns JSON structured like this:

{
    "children": [
        {
            "created": "2018-07-20T15:16:07.777535Z",
            "path": "api.demo/images/new-york",
            "type": "folder",
            "url": "https://imatag.com/api/v1/media/api.demo/images/new-york"
        },
        {
            "created": "2018-07-20T15:13:06.259863Z",
            "path": "api.demo/images/paris",
            "type": "folder",
            "url": "https://imatag.com/api/v1/media/api.demo/images/paris"
        }
    ],
    "created": "2018-07-20T15:04:33.221902Z",
    "next": null,
    "path": "api.demo/images",
    "previous": null,
    "type": "folder",
    "url": "https://imatag.com/api/v1/media/api.demo/images"
}

This endpoint lists the content of a folder at the given path. Note that the children list is paginated so you might have to iterate to get all children. The children attribute is only returned for the current folder and not for any subfolders. If you need the full hierarchy, you will need to recursively GET the url attribute of each subfolder.

HTTP Request

GEThttps://imatag.com/api/v1/media/<homedir>/<path>

URL Parameters

Parameter Required  Description
homedir false The user home directory where to list media from (e.g. jdoe).
path false The path of the subfolder(s) to list media from (e.g. images/2018) within a home directory.

 Response description

See Media object

Get a media

import requests

headers = {
    'Authorization': 'Token fd8fef6e430595edc3bab691d9a83230f0a56b99',
}
response = requests.get('https://imatag.com/api/v1/media/api.demo/images/paris/tour-eiffel.jpeg',
                        headers=headers)
curl https://imatag.com/api/v1/media/api.demo/images/paris/tour-eiffel.jpeg \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

The above command returns JSON structured like this:

{
    "created": "2018-07-20T15:15:49.548216Z",
    "image": "https://static1.imatag.com/54578,15ec5ca69f80719a",
    "path": "api.demo/images/paris/tour-eiffel.jpeg",
    "type": "image",
    "url": "https://imatag.com/api/v1/media/api.demo/images/paris/tour-eiffel.jpeg"
}

This endpoint retrieves information about the media at a given path.

HTTP Request

GEThttps://imatag.com/api/v1/media/<homedir>/<path>/<filename>

URL Parameters

Parameter Required  Description
homedir true The user home directory where to list media from (e.g. jdoe).
path false The folder(s) path where to store the media within your home directory (e.g. images/2018)
filename true The file name of the file that will be used on our servers (e.g. new-york.jpg)

 Response description

See Media object

 Register a new media

You can download this watermark file to run the example.

import requests

headers = {
    "Authorization": "Token fd8fef6e430595edc3bab691d9a83230f0a56b99",
    "Content-Type": "application/lmk",
}
lmk = open("./registration.lmk", "rb").read()
response = requests.put("https://imatag.com/api/v1/media/api.demo/uploads/2018/my-image.jpg",
                        data=lmk, headers=headers)

curl -X PUT \
  https://imatag.com/api/v1/media/api.demo/uploads/2018/my-image.jpg \
  -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99" \
  -H "Content-Type: application/lmk" \
  --data-binary @- < ./registration.lmk

The above command returns JSON structured like this:

{
    "created": "2018-08-10T14:56:23.110644Z",
    "image": "https://static3.imatag.com/54610,170479c60f05ff3e",
    "path": "api.demo/uploads/2018/my-image.jpg",
    "type": "image",
    "url": "https://imatag.com/api/v1/media/api.demo/uploads/2018/my-image.jpg"
}

This endpoint registers a previously watermarked media using the LMK file generated by the watermarking software.

HTTP Request

PUThttps://imatag.com/api/v1/media/<homedir>/<path>/<filename>

The content-type of the request must be application/lmk.

URL Parameters

Parameter Required Description
homedir true The home directory where to upload the media. This is generally your own username or another client folder for which you're granted permission (e.g. jdoe)
path false The optional subfolder path, within your home directory, where to store the media (e.g. images/2018)
filename  true  The file name & extension of the image to register. It will be its name on our servers & in your account.

Request content

The content of the request must be the full binary content of the LMK file generated by the watermarking software.

Response content

If the request is succesful, the response is the newly created Media object

Delete an existing media

import requests

headers = {
    "Authorization": "Token fd8fef6e430595edc3bab691d9a83230f0a56b99",
}
response = requests.delete("https://imatag.com/api/v1/media/api.demo/uploads/2018/my-image.jpg",
                           headers=headers)
curl -X DELETE \
  https://imatag.com/api/v1/media/api.demo/uploads/2018/my-image.jpg \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

This endpoint deletes and unregisters an existing media.

HTTP Request

DELETEhttps://imatag.com/api/v1/media/<homedir>/<path>/<filename>

URL Parameters

Parameter Required Description
homedir true The home directory where to upload the media. This is generally your own username or another client folder for which you're granted permission (e.g. jdoe)
path false The optional subfolder(s) where the media is stored (e.g. images/2018)
filename  true  The file name and extention of the media to delete

 Delete an existing folder

import requests

headers = {
    "Authorization": "Token fd8fef6e430595edc3bab691d9a83230f0a56b99",
}
response = requests.delete("https://imatag.com/api/v1/media/api.demo/uploads/2018",
                           headers=headers)
curl -X DELETE \
  https://imatag.com/api/v1/media/api.demo/uploads/2018 \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

This endpoint deletes a folder and all of its content (subfolders, images, documents, etc.) recursively. All media contained within will be unregistered.

HTTP Request

DELETEhttps://imatag.com/api/v1/media/<homedir>/<path>

URL Parameters

Parameter Required Description
homedir true The user home directory that contains the subfolder to delete (e.g. jdoe).
path true The path of the subfolder to delete (e.g. images/2017).

Matches

Web Matches

This endpoint lists all web matches found (similar and watermarked) on the Internet by our crawlers.

HTTP Request

GEThttps://imatag.com/api/v1/matches/web

import requests

headers = {
    "Authorization": "Token fd8fef6e430595edc3bab691d9a83230f0a56b99",
}
response = requests.get("https://imatag.com/api/v1/matches/web", headers=headers)
curl https://imatag.com/api/v1/matches/web/ \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

The above command returns JSON structured like this:

{
    "count": 178,
    "next": "https://imatag.com/api/v1/matches/web/?cursor=cD0xNTMyODAyMjk0MzAzJmM9MTc4",
    "previous": null,
    "results": [
        {
            "created": "2018-08-10T14:21:50.568016Z",
            "paths": [
                {
                    "created": "2018-07-20T15:15:43.305448Z",
                    "image": "https://static3.imatag.com/54581,15ec5c5961692db6",
                    "path": "api.demo/images/paris/moulin-rouge.jpeg",
                    "type": "image",
                    "url": "https://imatag.com/api/v1/media/api.demo/images/paris/moulin-rouge.jpeg"
                }
            ],
            "query_page_url": "http://lisaballtraveldesign.com/category/slides/page/2/",
            "query_url": "http://lisaballtraveldesign.com/wp-content/uploads/Paris2Free-600x350.jpeg",
            "type": "web",
            "url": "https://imatag.com/api/v1/matches/94991655/",
            "watermarked": false
        },
        {
            "created": "2018-08-10T13:31:33.662711Z",
            "paths": [
                {
                    "created": "2018-07-20T15:15:47.158967Z",
                    "image": "https://static2.imatag.com/54582,15ec5c8cca8206f8",
                    "path": "api.demo/images/paris/louvre.jpeg",
                    "type": "image",
                    "url": "https://imatag.com/api/v1/media/api.demo/images/paris/louvre.jpeg"
                }
            ],
            "query_page_url": "http://www.ojornaldeuberlandia.com.br/2017/12/05/governo-brasileiro-leva-startups-franca-em-busca-de-investidores/",
            "query_url": "http://www.ojornaldeuberlandia.com.br/wp-content/uploads/2017/12/WhatsApp-Image-2017-12-05-at-10.08.19.jpeg",
            "type": "web",
            "url": "https://imatag.com/api/v1/matches/94988160/",
            "watermarked": false
        },
        "..."
    ]
}

Filtering (non-)watermarked matches & by date

import requests

headers = {
    "Authorization": "Token fd8fef6e430595edc3bab691d9a83230f0a56b99",
}
response = requests.get("https://imatag.com/api/v1/matches/web", params={
    'watermarked': True, 'date': '2018-08-02'},
                        headers=headers)

response = requests.get("https://imatag.com/api/v1/matches/web", params={
    'watermarked': True, 'date_gt': '2018-08-01', 'date_lte': '2018-08-02T12:45:00Z'},
    headers=headers)
curl 'https://imatag.com/api/v1/matches/web/?watermarked=true&date=2018-08-02' \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

curl 'https://imatag.com/api/v1/matches/web/?watermarked=true&date_gt=2018-08-01&date_lte=2018-08-02T12:45:00Z' \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

Query Parameters

Parameter Default Description
watermarked null If set to true, only watermarked results will be shown, if set to false, only non-watermarked results will be shown
date null If set, only results found on that exact date (or exact date & time) will be shown. This cannot be combined with other date lookups (gt, lt, etc.)
date_lte null If set, only results found on that date or earlier will be shown
date_gte null If set, only results found on that date or later will be shown
date_lt null If set, only results found earlier than that date will be shown
date_gt null If set, only results found later than that date will be shown

 Response description

Attribute Description
count Total number of matches
next url of the next matches in the sequence (null if end is reached)
previous url of the previous matches in the sequence (null at the start)
results list of web match objects (see Web Match object) sorted by match date, newest first

Web Match Object

Attribute Description
url The URL of this match (direct link)
created  The date of creation of the match (ISO8601)
type  The type of match (always "web")
watermarked Whether the watermark was found (boolean)
query_url The original URL of the query media
query_page_url The original URL of the page where the media was found
paths The list of corresponding media objects in your account (see Media object)

Press Matches

This endpoint lists all matches found in the press.

HTTP Request

GEThttps://imatag.com/api/v1/matches/press

import requests

headers = {
    "Authorization": "Token fd8fef6e430595edc3bab691d9a83230f0a56b99",
}
response = requests.get("https://imatag.com/api/v1/matches/press", headers=headers)
curl https://imatag.com/api/v1/matches/press/ \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

The above command returns JSON structured like this:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "created": "2018-08-03T12:35:23.371022Z",
            "issue": {},
            "page_number": 1,
            "paths": [
                {
                    "created": "2018-07-20T15:20:15.890934Z",
                    "image": "https://static2.imatag.com/54580,15ec6954eac4981b",
                    "path": "api.demo/images/new-york/brooklyn-bridge.jpeg",
                    "type": "image",
                    "url": "https://imatag.com/api/v1/media/api.demo/images/new-york/brooklyn-bridge.jpeg"
                }
            ],
            "type": "press",
            "url": "https://imatag.com/api/v1/matches/94457659/",
            "watermarked": true
        }
    ]
}

Query Parameters

Parameter Default Description
watermarked null If set to true, only watermarked results will be shown, if set to false, only non-watermarked results will be shown
date null If set, only results found on that exact date (or exact date & time) will be shown. This cannot be combined with other date lookups (gt, lt, etc.)
date_lte null If set, only results found on that date or earlier will be shown
date_gte null If set, only results found on that date or later will be shown
date_lt null If set, only results found earlier than that date will be shown
date_gt null If set, only results found later than that date will be shown

 Response description

Attribute Description
count Total number of matches
next url of the next matches in the sequence (null if end is reached)
previous url of the previous matches in the sequence (null at the start)
results list of press match objects (see Press Match object) sorted by match date, newest first

Press Match Object

Attribute Description
url The URL of this match (direct link)
created  The date of creation of the match (ISO8601)
type  The type of match (always "press")
watermarked Whether the watermark was found or not (boolean)
issue Press issue where the media was found (see Press Issue object)
page_number Page of the issue where the image was found
paths The list of corresponding media objects in your account (see Media object)

Press Issue Object

Attribute Description
name Name of the publication
date Date of the publication (ISO8601, date only)

Crawling

The crawling API controls web crawling specific web sites.

Crawling Session

A crawling session groups crawls of a website and defines the common parameters of those crawls. The first crawl is initiated (seeded) on the start_urls of the session. Links to pages internal to the domain are then added recursively to the list of pages to visit. Links to images are stored and visually matched to your media if the search option is enabled. Subsequent crawls start from the state of the latest crawl in the session and continue the crawling in a recursive manner.

Crawling Session Object

Attribute Description
url The URL of the session
id The unique identifier of the session
ctime Starting date of the session
mtime Modification date of the session (date of latest crawl)
crawl_delay Maximum duration of each crawl
search Whether to search for matches in your media
download_delay Delay between successive requests to the same domain
download_timeout Time to wait before assuming the connection timed out
start_urls List of urls the session was initiated on
batches List of URLs of crawling batches associated with the session (see Crawling Batch Object)

List all available sessions

HTTP Request

GEThttps://imatag.com/api/v1/crawling/sessions/

import requests

headers = {
    "Authorization": "Token fd8fef6e430595edc3bab691d9a83230f0a56b99",
}
response = requests.get("https://imatag.com/api/v1/crawling/session/", headers=headers)
curl https://imatag.com/api/v1/crawling/sessions/ \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

The above command returns JSON structured like this:

{
    "next":null,
    "previous":null,
    "results":[
            {
                    "url":"https://imatag.com/api/v1/crawling/sessions/1/",
                    "id":1,
                    "ctime":"2018-08-09T12:19:57.849603+02:00",
                    "mtime":"2018-08-09T12:19:57.849640+02:00",
                    "crawl_delay":300,
                    "search":true,
                    "download_delay":0.1,
                    "download_timeout":15.0,
                    "start_urls": [
                                  "https://imatag.com/"
                    ],
                    "batches": [
                               "https://imatag.com/api/v1/crawling/batches/2/",
                               "https://imatag.com/api/v1/crawling/batches/1/"
                    ]
            }
     ]
}

Response description

Attribute Description
next url of the next sessions in the sequence (null if end is reached)
previous url of the previous sessions in the sequence (null at the start)
results list of Crawling Session objects (see Crawling Session object)

Get a session

import requests

headers = {
    'Authorization': 'Token fd8fef6e430595edc3bab691d9a83230f0a56b99',
}
response = requests.get('https://imatag.com/api/v1/crawling/sessions/1/',
                        headers=headers)
curl https://imatag.com/api/v1/crawling/sessions/1/ \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

The above command returns JSON structured like this:

{  
   "url":"https://imatag.com/api/v1/crawling/sessions/1/",
   "id":1,
   "ctime":"2018-08-09T12:19:57.849603+02:00",
   "mtime":"2018-08-09T12:19:57.849640+02:00",
   "crawl_delay":300,
   "search":true,
   "download_delay":0.1,
   "download_timeout":15.0,
   "start_urls":[  
      "https://imatag.com/"
   ],
   "batches":[  
      "https://imatag.com/api/v1/crawling/batches/2/",
      "https://imatag.com/api/v1/crawling/batches/1/"
   ]
}

This endpoint retrieves information about a specific crawling session.

HTTP Request

GEThttps://imatag.com/api/v1/crawling/sessions/<session_id>/

URL Parameters

Parameter Required  Description
session_id true The unique id of the session to retrieve information on.

Response description

See Crawling Session object

Crawling Batch

A crawling batch stores information gathered during a crawl. Each time a crawl is run, a new crawling batch object is created at the end of it.

Crawling Batch Object

Attribute Description
url The URL of the crawling batch
id The unique identifier of the crawling batch
ctime Starting time at which the batch was created (end of crawl)
session A link to the crawling session associated with this batch (see Crawling Session object)
images Hash of information on the images found in the crawl, detailled below
images.count Number of images found in the crawl
images.log URL to download the list of images found during the crawl, in gzipped CSV format (optional)
images.tar URL to download the images found during the crawl, in TAR format (optional)
pages Hash of information on the pages found in the crawl, detailled below
pages.count Number of pages found in the crawl
pages.log URL to download the list of pages found during the crawl, in gzipped CSV format (optional)
pages.warc URL to download the requests and responses corresponding to pages found during the crawl, in gzipped WARC format (optional)

List all available batches

HTTP Request

GEThttps://imatag.com/api/v1/crawling/batches/

import requests

headers = {
    "Authorization": "Token fd8fef6e430595edc3bab691d9a83230f0a56b99",
}
response = requests.get("https://imatag.com/api/v1/crawling/batches/", headers=headers)
curl https://imatag.com/api/v1/crawling/batches/ \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

The above command returns JSON structured like this:

{
   "next" : null,
   "results" : [
      {
         "ctime" : "2018-08-13T15:51:23.186005+02:00",
         "session" : "https://imatag.com/api/v1/crawling/sessions/1/",
         "url" : "https://imatag.com/api/v1/crawling/batches/13/",
         "pages" : {
            "count" : 539,
            "warc" : "https://static3.imatag.com/54661,1729c1e94282b9aa",
            "log" : "https://static4.imatag.com/54686,1729c1e74e629d47"
         },
         "id" : 13,
         "images" : {
            "count" : 2647,
            "log" : "https://static1.imatag.com/54682,1729c13dd6694192",
            "tar" : "https://static2.imatag.com/54662,1729c184b181ac39"
         }
      }
   ],
   "previous" : null
}

Response description

Attribute Description
next url of the next batches in the sequence (null if end is reached)
previous url of the previous batches in the sequence (null at the start)
results list of Crawling Batch objects (see Crawling Batch object)

Get a batch

import requests

headers = {
    'Authorization': 'Token fd8fef6e430595edc3bab691d9a83230f0a56b99',
}
response = requests.get('https://imatag.com/api/v1/crawling/batches/1/',
                        headers=headers)
curl https://imatag.com/api/v1/crawling/batches/1/ \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

The above command returns JSON structured like this:

{
   "id" : 13,
   "pages" : {
      "log" : "https://static1.imatag.com/54686,1729c1e74e629d47",
      "warc" : "https://static4.imatag.com/54661,1729c1e94282b9aa",
      "count" : 539
   },
   "session" : "https://imatag.com/api/v1/crawling/sessions/1/",
   "images" : {
      "tar" : "https://static2.imatag.com/54662,1729c184b181ac39",
      "log" : "https://static1.imatag.com/54682,1729c13dd6694192",
      "count" : 2647
   },
   "url" : "https://imatag.com/api/v1/crawling/batches/13/",
   "ctime" : "2018-08-13T15:51:23.186005+02:00"
}

This endpoint retrieves information about a specific crawling batch.

HTTP Request

GEThttps://imatag.com/api/v1/crawling/batches/<batch_id>/

URL Parameters

Parameter Required  Description
batch_id true The unique id of the batch to retrieve information on.

Response description

See Crawling Batch object

Classification

Image Classifiers

This endpoint performs image classification based on Deep Learning models.

Classifier Object

Attribute Description
name Name of the classifier
num_classes Number of different output classes
image_size Maximum supported image size (larger images will be resized, with no gain in classification performance)

A classifier determines to which classes an image belong by analyzing its pixels. It returns the most likely classes the image belongs to, along with an approximate probability of belonging to each class.

List all available classifiers

HTTP Request

GEThttps://imatag.com/api/v1/classifiers/

import requests

headers = {
    "Authorization": "Token fd8fef6e430595edc3bab691d9a83230f0a56b99",
}
response = requests.get("https://imatag.com/api/v1/classifiers/", headers=headers)
curl https://imatag.com/api/v1/classifiers/ \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

The above command returns JSON structured like this:

{
        "next":null,
        "previous":null,
        "results":[
                {
                        "name": "mxnet-resnet-152-10k",
                        "num_classes": 10731,
                        "image_size": 224
                },
                {
                        "name": "tensorrt-resnet-50-yahoo-opennsfw",
                        "num_classes": 2,
                        "image_size": 224
                },
                {
                        "name":"tensorrt-inception3-6k",
                        "num_classes":6012,
                        "image_size":299
                }
        ]
}

Response description

Attribute Description
next url of the next matches in the sequence (null if end is reached)
previous url of the previous matches in the sequence (null at the start)
results list of classifier objects (see Classifier object)

Get a classifier

import requests

headers = {
    'Authorization': 'Token fd8fef6e430595edc3bab691d9a83230f0a56b99',
}
response = requests.get('https://imatag.com/api/v1/classifiers/tensorrt-inception3-6k/',
                        headers=headers)
curl https://imatag.com/api/v1/classifiers/tensorrt-inception3-6k/ \
 -H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99"

The above command returns JSON structured like this:

{
        "name":"tensorrt-inception3-6k",
        "num_classes":6012,
        "image_size":299
}

This endpoint retrieves information about a classifier.

HTTP Request

GEThttps://imatag.com/api/v1/media/<classifier_name>/

URL Parameters

Parameter Required  Description
classifier_name true The name of the classifier to retrieve information on.

Response description

See Classifier object

Perform classification on an image

import requests

headers = {
    "Authorization": "Token fd8fef6e430595edc3bab691d9a83230f0a56b99",
    "Content-Type": "image/jpeg",
}
image = open("./tour-eiffel.jpeg", "rb").read()
response = requests.put("https://imatag.com/api/v1/classifiers/tensorrt-inception3-6k/",
                        data=image, headers=headers)
curl -X PUT \
https://imatag.com/api/v1/classifiers/tensorrt-inception3-6k/ \
-H "Authorization: Token fd8fef6e430595edc3bab691d9a83230f0a56b99" \
-H "Content-Type: image/jpeg" \
--data-binary @- < tour-eiffel.jpeg

The above command returns JSON structured like this:

{
        "tags":
                {
                        "fr": [
                                        {
                                                "tag":"point de repère",
                                                "prob": 0.79
                                        },
                                        {
                                                "tag":"nuit",
                                                "prob": 0.65
                                        },
                                ...
                         ],
                          "en": [
                                        {
                                                "tag": "landmark",
                                                "prob": 0.79
                                        },
                                        {
                                                "tag": "night",
                                                "prob": 0.65
                                        },
                                        {
                                                "tag": "tower",
                                                "prob": 0.63
                                        },
                                ...
                         ]
                  }
}

This endpoint performs classification on the uploaded image using the classifier.

You can download this file to run the example.

HTTP Request

PUThttps://imatag.com/api/v1/media/<classifier_name>/

URL Parameters

Parameter Required  Description
classifier_name true The name of the classifier to use for classification.

Request content

The content of the request must be the full binary content of the image file. The Content-Type header must be set according to the image format.

Response description

Attribute Description
tags Hash of sorted list of tag objects (see Tag object) associated with the image, with one list for each supported language ("en", "fr" at the moment).

Tag Object

Attribute Description
tag The description of the tag
prob The probability that this image has this tag

Watermarking Software

Depending on your service plan, you might have access to the IMATAG watermarking software. It is used to watermark your images before registering them on the API media endpoint. This enables you to have the fastest possible watermarking pipeline, as well as making your delivery process independent from any IMATAG API calls, ensuring the highest possible reliability.

Download

Go to your IMATAG account and scroll down to the "Watermarking software" section.

Installation

No installation is needed. The software you downloaded is a binary which can be executed to watermark images directly. It has no dependencies.

Before execution, you will have to make sure that:

Software usage

Assuming your current directory contains lamark, public_key.derand input_image.jpg

import subprocess

subprocess.check_call(["lamark",
                       "input_image.jpg",
                       "output_image.jpg", "registration.lmk",
                       "public_key.der"])
./lamark input_image.jpg output_image.jpg registration.lmk public_key.der

The above should produce the following output

LAMARK image watermarking tool 2.3.4
Copyright 2015-2018 Lamark

This software is based in part on the work of the Independent JPEG Group
Using fdlibm Copyright (C) 1993 by Sun Microsystems, Inc. All rights reserved.

And create output_image.jpg and registration.lmk in your current directory.

lamark [options] <input_image.jpg> <output_image.jpg> <registration.lmk> <public_key.der>

pameters Description
<input_image.jpg> The full-resolution input image, in JPEG format
<output_image.jpg> The full-resolution output wartermarked image, in JPEG format
<registration.lmk> The encrypted registration data that should be sent on the media endpoint
<public_key.der> The encryption key downloaded from your IMATAG account. Used to encrypt the registration file
options Description
-t Transactional watermarking

Output and exit codes

The software always outputs version and licence information on stderr

Advanced usage: Transactional watermarking

./lamark    input_image.jpg output_image_1.jpg registration_1.lmk public_key.der
./lamark -t input_image.jpg output_image_2.jpg registration_2.lmk public_key.der

The "Transactional watermarking" -t option can be used to limit storage and bandwidth usage if you watermark the same original image many times. The drawback is that it will make your scripts state-full and generally more complex.

It works like this: the first time you watermark an image, do not use the -t option and register the registration.lmk file. When you watermark the same image again, add the -t option. This will make the new registration.lmk file much smaller. You can register it as usual.

What happens is that the normal or in this case the first registration.lmk file contains a smaller version of your image which is used by our servers to identify your image (it is also used to generate thumbnails for the web interface). If you watermark the same image again, you don't need to send it again and the -t option allows you not to. To identify the original we compute a hash of its pixels and which is included in the registration.lmk file. When we register a transactional registration.lmk, we find the file which was already registered with the same hash and use that one. This means that if you haven't registered the first one or have modified it's content in any way since then, you will get an error when you try to register the transactional registration.lmk. Note that we look at the pixel data so if you modify only the metadata you should be OK.