An API for searching inside an image for occurances of a set of images.

The Logoseer API allows the user to upload a set of images (a dataset) and then upload an image (a search image) in which to search for the images in a given dataset. For more information, see the documentation below or register as a user here and check out the demo here.

Quick links

• Register a new user
• Create a dataset
• Upload an image to a dataset
• Add a user to a dataset
• Upload a search image
• Upload and search a search image
• View search history
• Demo the API
• See your account history

Updates

October 2016: a TrademarkVision dataset (name: TMV, id: 111) has been added and is accessible to all users. It will, by default, be included in any search that does not specify datasets to search and can be included in a search with specified datasets by including the id 111.

Documentation

API Concepts

Datasets

Collections of images. A dataset has a name and can be owned/accessed by multiple users. Located at /datasets/.

Images

Individiual logos or trademarks to search for in a search image; images belong to a Dataset. Located at /images/.

Search Images

The image you are trying to find logos in. Located at /searchimages/. Images are owned by a user and are associated with one or many datasets that they have been searched against.

Search

The action endpoint to execute a search. Located at /search/

Authentication

The Logoseer API uses token-based authentication. If making a cURL request the token should be added as an Authorization header and can be accessed by doing a POST request to /api-token-auth/ with the data {"username":username, "password":password} like this:

curl http://logoseer.com/api-token-auth/ -X POST -d '{"username": "<username>", "password": "<password>"}' -H "Content-Type: application/json"

which will get you a response like this:

{
  "token":"<token string>"
}

which you should pass in like this:

curl -X POST -H "Authorization: Token <authtoken>"...<rest of request>

Datasets

Creating a dataset

While logged in, use the form located at /datasets/create/ or:

With curl

Make a POST request to /datasets/ with the name for the dataset.

curl http://logoseer.com/datasets/ -X POST -d '{"name":<dataset_name>}' -H "Authorization: Token <authtoken>" -H "Content-Type: application/json"

The response will look like this:

{
  "id": <dataset_id>,
  "name":"<dataset_name>",
  "images":[],
  "owners":[
    <your_id>
  ]
}

Use the ID returned in the response to upload images to this dataset and to search against it.

Accessing your datasets

To get a list of owned datasets, make an authenticated GET request to /datasets/.

curl http://logoseer.com/datasets/ -X GET -H "Authorization: Token <authtoken>" -H "Content-Type: application/json"

Response:

[
  {
    "id": <dataset_id>,
    "name": "<dataset_name>",
    "owners": [
      <owner_id>
      ]
  },
  {
    "id": <dataset_id>,
    "name":"<dataset_name>",
    "owners":[
      <owner_id>
    ]
  }
]

To get information about a single dataset make an authenticated GET request to /datasets/<dataset_id>.

To see a gallery view of the images in a dataset, go to /datasets/<dataset_id>/gallery.

Adding users to a dataset

If you want to give another user access to a dataset you've uploaded, you can go to /datasets/adduser/ and enter in their email address and select the dataset you wish to add them to.

Images

Uploading images to a dataset

While logged in, use the form located at /images/create/

With curl

Upload images to a dataset by making a POST request to /images/ with the image file and details about the image.

Additional fields

• Tag: your ID field for the image. Field has a max length of 20.
• Classtype: field for additional classification. Field has a max length of 20.
• Wordmark (optional): field for additional identifying wordmark for the image. Field has a max length of 20.

curl http://logoseer.com/images/ -i -X POST -H "Content-Type: multipart/form-data" -H "Authorization: Token <authtoken>"
    -F "image=@<filename>" -F "tag=<tag>" -F "classtype=<classtype>" -F "dataset=<dataset_id>"

Accessing images

To get a list of your images, make an authenticated GET request to /images/.

You'll get a response like this:

[
    {
        "id": 1,
        "tag": "1",
        "classtype": "primary mark",
        "image": "http://localhost:8000/media/dataset_images/1-primary_mark_gKva5iz.png",
        "wordmark": "",
        "dataset": 1
    },
    {
        "id": 2,
        "tag": "10",
        "classtype": "secondary mark",
        "image": "http://localhost:8000/media/dataset_images/10-secondary_mark_CCGbpY2.png",
        "wordmark": "",
        "dataset": 1
    }
]

To get information about an individual image, make an authenticated GET request to /images/<image_id>.

Image file retrieval

To retrieve an image file directly, make an authenticated GET request to /images/file/<dataset>/<tag>.

Search images

Uploading a search image

While logged in, use the form at /searchimages/create to upload an image without doing a search.

With curl

To upload an image without searching against it, make a POST request to /searchimages/ with the image and datasets to search against in the future.

curl http://logoseer.com/searchimages/ -i -X POST -H "Content-Type: multipart/form-data" -H "Authorization: Token <authtoken>"
                    -F "image=@<filename>" -F "datasets=[<dataset_id>]"

*Note: previous documentation indicated datasets should be sent as datasets=<dataset_id>; a keyword of "dataset" or "datasets" will work, and the dataset ids can be sent as a list if there's more than one "datasets=[1, 2, 3]" or a single id if there's only one "datasets=1".

You'll get a response like this:

{
      "id": 131,
      "owner": 1,
      "image": "http://logoseer.com/media/user_images/<filename>.png",
      "datasets": [
            1
        ]
  }

Accessing search images

To get a list of your search images, make an authenticated GET request to /searchimages/.

You'll get a response like this:

[
    {
        "id": 128,
        "owner": 1,
        "image": "http://logoseer.com/media/user_images/bama-1_ildBexf.png",
        "datasets": [
            1
        ]
    },
    {
        "id": 129,
        "owner": 1,
        "image": "logoseer.com/media/user_images/lsu-4_hfh47Xh.png",
        "datasets": [
            2
        ]
    },

To get information about an individual search image, make an authenticated GET request to /searchimages/<searchimage_id>.

Searching

Searching an image

To upload and search against an image, make a POST request to /search/ with the image and the dataset(s) to search against.

curl http://logoseer.com/search/ -i -X POST -H "Content-Type: multipart/form-data" -H "Authorization: Token <authtoken>"
                        -F "image=@<filename>” -F "datasets=[<dataset_id>]”

You can also use the form at /search/create/ to upload and search an image.

To re-do a search on an already uploaded image, make a GET request to /search/ with the image ID as a query parameter.

curl http://logoseer.com/search/?searchimage=<searchimage_id> -H "Content-Type: application/json" -H "Authorization: Token <authtoken>"

The response will contain a list of images from the given dataset that were located in the search image as well as a box outlining where in the search image it was found. The output below indicates that image 20 was found in a box bounded by 117 on the top, 354 on the right, 249 on the left, and 212 on the bottom. All distances are measured from the top left corner of the search image.

The output will also return confidence for the matches it made, 89% in the example below.

Example output:

HTTP/1.0 200 OK
Date: Mon, 13 Jun 2016 16:38:13 GMT
Server: WSGIServer/0.1 Python/2.7.10
Vary: Accept
X-Frame-Options: SAMEORIGIN
Content-Type: application/json
Allow: GET, POST, HEAD, OPTIONS

{
    "height": 612,
    "matches": [
        {
            "bbox": {
                "top": 117,
                "right": 354,
                "bottom": 212,
                "left": 249
            },
            "confidence": 0.891231,
            "image": {
                "class": "secondary mark",
                "dataset": "alabama"
                "id": 5,
                "tag": "4",
            }
        }
    ],
    "searchimage_id": 130,
    "snapshot_id": 2201,
    "snapshot_url": "http://logoseer.com/snapshots/file/2201",
    "width": 792,
}

If more than one image is found the matches list will have more than one item in it; if an image is found more than once it will appear in the list as many times as it is found.

To see your history of searches and re-execute them, go to /searchimages/history.

Search Snapshots

Retrieving search results from a snapshot

Results from previous searches are stored in search snapshots.

To retrieve results from a previous search, make a GET request to /snapshots/<snapshot_id>.

curl http://logoseer.com/snapshots/<snapshot_id> -i -X GET -H "Authorization: Token <authtoken>"

Example output for /snapshots/2201 (the search shown in the previous section):

HTTP/1.0 200 OK
Date: Mon, 13 Jun 2016 16:38:13 GMT
Server: WSGIServer/0.1 Python/2.7.10
Vary: Accept
X-Frame-Options: SAMEORIGIN
Content-Type: application/json
Allow: GET, POST, HEAD, OPTIONS

{
    "height": 612,
    "matches": [
        {
            "bbox": {
                "top": 117,
                "right": 354,
                "bottom": 212,
                "left": 249
            },
            "confidence": 0.891231,
            "image": {
                "class": "secondary mark",
                "dataset": "alabama"
                "id": 5,
                "tag": "4",
            }
        }
    ],
    "searchimage_id": 130,
    "snapshot_id": 2201,
    "snapshot_url": "http://logoseer.com/snapshots/file/2201",
    "width": 792,
}

Updating search results in an existing snapshot

It is possible to manually edit the results of previous search snapshots.

To update results in a previous snapshot, make a POST request to /snapshots/update/<snapshot_id> with the matches parameter.

curl http://logoseer.com/snapshots/update/<snapshot_id> -i -X POST -H "Content-Type: multipart/form-data" -H "Authorization: Token <authtoken>"
                    -F 'matches=[<match1>,<match2>,...]'

The matches parameter should be a properly formatted JSON list of matches, where each match has the left, top, right, bottom, dataset, and tag fields. Note that JSON format mandates that the fields must be encased in double quotes, not single. Example (with 2 matches):

 -F 'matches=[{"top": 117, "right": 354, "left": 249, "bottom": 212, "dataset": "alabama", "tag": "4"}, {"top": 201, "right": 304, "left": 102, "bottom": 352, "dataset": "alabama", "tag": "2"}]'

The next time that these snapshot results are retrieved, they will show the updated matches.

Snapshot image file retrieval

To retrieve the snapshot drawing file directly, make an authenticated GET request to /snapshots/file/<snapshot_id>.