Developer Centre

Authentication | Creating Searches | Querying Search Data | API Documentation

Authentication

Unless otherwise stated, you must authenticate all requests that you make to the API. This is done by passing your API key in the "X-API-Key" HTTP header. For instance:
POST /search HTTP/1.1
Host: api.infringement.report
X-Api-Key: 123456789abcdef

Creating Searches

Try it out and see API docs

To get data about websites who are using your images, you must create a search. A search is a request where you send one or more images to the API, so that our system can find the websites using them. Depending on the amount of images you send, their popularity across the internet (images used on more websites take longer to search), and the current load on the system, it could take several seconds for us to complete a search.

Because of the way that these search engines work, usages can be found even if the image has been renamed or edited, making this data critical for copyright enforcement firms. This service does not attempt to detect false positives, or confirm that the image actually exists on the page - it provides raw data from search engines only.

Lists

All searches create an image list, even if only one image is submitted. We will provide a list_id within the search response, and you can optionally set a label to help you identify the images inside the list.

This endpoint accepts the following parameters:

Search

Request
Endpoint: https://api.infringement.report/2.0/search
Authentication required
Response
{
    "images": ["http:\/\/www.domain.com\/image.jpg"],
    "list_label": "My test list"
}
{
    "status": true,
    "code": 100,
    "list_id": 12345
}

Waiting for searches to complete

When you start a search, the API will immediately respond to your request with a list_id and the search will be completed in the backgroud. You can then poll the list resource (/list or /list/{list_id}) until it returns search_in_progress=0. Alternatively you can begin polling the /list/{list_id}/query endpoint until it responds with search data. Note: /query will begin to return data as soon as it is available, even if some image searches have not completed yet.

Querying Data

Try it out and see API docs

After a search has completed, the result data will be saved and becomes queryable through the /list/{list_id}/query endpoint. There are several manipulations that you can do to the data.

Sorting and Pagination

You can specify the sorting of results by passing the "sort" parameter with the name of the metric you want to sort by, and "asc" or "desc". For instance:

By default, we will return 1,000 results per request, so you will need to use pagination to get all results for a large list of images. To do this you should pass the parameters "rows" (number of rows per page) and "start" (the start row of this page).

Grouping Results

The results can either be ungrouped or grouped. When they're ungrouped, all search results will be returned in one object. When grouped, search results will be returned as the child of the grouping metric (i.e. results per host).
Specify the grouping metric using the "group_by" parameter. Currently, the only metrics which results can be grouped by are: host, image_id, search_timestamp, and search_image_url.

Filtering

Filtering data to match specific requirements is easy .

Filter Syntax

Filters are applied to your results by specifying a metric name, an operator, and a value.

Filters must be specified in JSON object using '[metric]-[operator]' as the key. An example of a filter is: {"host-cont":"domain.com"} (host contains "domain.com")

Metric Type Operators available
title string eql, cont, starts, ends
description string eql, cont, starts, ends
url string eql, cont, starts, ends
host string eql, cont, starts, ends
protocol string eql, cont, starts, ends
image_url string eql, cont, starts, ends
image_width number gt, lt, eql
image_height number gt, lt, eql
image_width_on_page number gt lt, eql
image_height_on_page number gt, lt, eql
image_id number gt, lt, eql
search_timestamp date before, after, between

Operator Meanings

Operator Means Use on Metric Type
eql Equals string, number
cont Contains string
starts Starts with string
ends Ends with string
gt Greater Than number
lt Equals number
before Before date date
after After date date
between Between two dates date

Filter Example

{"query":{
    "filter":{
      "url-cont":"domain",
      "title-ends":"Brand"
      "image_width-gt":1000,
      "search_timestamp-between":"2017-10-01T01:01:01Z TO 2017-11-01T01:01:01Z"
    }
  }
}

Lists

Lists are collections of images and image search results. A list can contain one or more images, and is broadly used for querying results and firing notifications.

Lists are controlled via a standard REST endpoint which accepts GET (read list properties or retrieve a list of lists), POST (create new list), PATCH (update existing list), and DELETE (delete list and all data). For more information about lists or their properties, see the API documentation.

Notifications

Notifications of new domains found in lists can be sent up to daily - we can send either an email or a POST request to a public URL, containing data in a variety of formats.
Notifications can be sent up to once per day, and can be run on an entire list, or only a subset of results (via filters).

Notifications are controlled via a standard REST endpoint which accepts GET (read notification properties or retrieve a list of notifications), POST (create new notification), PATCH (update existing notification), and DELETE (delete a notification). For more information about lists or their properties, see the API documentation.