interlocutrix

Welcome

TrademarkVision is the world’s leading image recognition for trademarks search system. We provide an API so our image recognition technology can integrate into your search system. Contact us with any queries.

This guide is for API v4. If you have integrated with us using older versions of the API, please refer to the migrate section of this documentation. You can still access our API v3.

Simple integration samples are also available in our examples.

Authentication

In order to start using the API, you'll need a token.

You should store the user and token values as they are required for all API requests.

Once you have obtained a token, you can verify to make sure you can still authenticate.

You can obtain a token for a specific user by sending a POST request with your TrademarkVision username and password to /api/v4/login/.

                
curl -F "username=test@test.com"
     -F "password=secret"
     /api/v4/login/
                
            

If the request is successful, you will receive a JSON response with your authentication token:


{
    "success": true,
    "token": "2uy-420a8efff7f882afc20d",
    "user": 32
}
            

Verify your token:

                
curl /api/v4/verify_token/2uy-420a8efff7f882afc20d/32
                
            

If your token is still valid, you will receive the following response:


{
    "success": true
}
            

Segment & search

If you are using an image that has more than one device, or a device and some text, you can use TrademarkVision's segmentation tool to determine which portions of the image to search.

Each segment has information pertaining to whether it is a device or a word. Each segment has a box (upper, left, lower, right) in reference to the original image. The is_selected flag indicates which device segment is the largest.

To search against a particular logo segment, the above information can be passed into the same Image Search view /api/v4/search/ as described previously, but rather than uploading a file, we use the "image" field (="image_id" from the "segment" JSON) and optional parameters fields of "upper", "left", "lower", "right". See the example on the right for more details.

Alternatively, if you supply the auto_segment parameter to the search request, our system will attempt to automatically detect the optimal segment in the image, and search that.

Note: For simple images, the automatic segment selection will usually suffice. For more complicated images or use cases, you may wish to specify the segment explicitly.

For example:

                
curl -F "file=@/home/user/hello.jpg"
     -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     /api/v4/segment/
                
            

On success, the API returns your image's details in the following format:


{
    "image_id": 831,
    "image_h": 114,
    "image_w": 443,
    "invert": false,
    "segments": [
        {
            "id": 2317,
            "segment_type": "device",
            "right": 112,
            "lower": 110,
            "left": 4,
            "upper": 4,
            "is_selected": true
        }
    ]
}
            

 

Using the segment details while running a search:

                
curl -F "image_id=831"
     -F "left=4" -F "right=112" -F "lower=110" -F "upper=4"
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"
     /api/v4/search/
                
            

 

Automatic segmentation:

                
curl -F "image_id=831"
     -F "auto_segment=1"
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"
     /api/v4/search/
                
            

Polygon segmentation

In order to more fine-grained control over which part of the image is searched, the segmentation may be specified as a polygon. This allows more flexibility than the standard rectangular segmentation specified above.

A polygon is specified as a list of [x, y] coordinates. For example, an irregular pentagon with sides approx 20px could be specified as: [[20, 20], [40, 20], [45, 30], [30, 40], [15, 30]].

Whitespace in the polygon coordinates is optional, so [ [20, 20], [... is logically equivalent to [[20,20],[....

Using the polygon segmentation while running a search:

                
curl -F "image_id=831"
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"
     -F "polygon=[[20, 20], [40, 20], [45, 30], [30, 40], [15, 30]]"
     /api/v4/search/
                
            

Text search

In addition to image search, you can perform any text search using the TrademarkVision API.

Use the text_search parameter to specify any text. Text search can be combined with boolean operators, wildcards and fuzzyness operators to fine tune your results.

mark AND trade AND NOT jack

Will include all trademarks which include mark AND trade but do not include jack. It is possible to group search terms too:

(mark AND trade) OR jack

Will include all trademarks which include mark AND trade or jack by its own. Similarly:

mark AND (trade OR jack)

Will include all trademarks which include mark AND trade or mark AND jack.

In addition to logical operators, you can the following wildcards:

  • *: which will match zero to many characters
  • ?: which will match zero or one character

For example

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?text_search=(trade AND mark) OR jack"
                
            
                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?text_search=(tr*de AND m*k) OR jac?"
                
            

Keyword search

The API supports direct keyword and codes search. This allows you to search for images using Vienna codes, 650-965-3945 and Australian image descriptors.

Use keyword_search in your search query to specify any list of keywords. By default, if no type of keyword is specified, the API searches amongst all of the types of keywords.

To specify a type, you can do the following:

  • VC-xx.yy.zz: will match Vienna codes
  • US-xx.yy.zz: will match US design codes
  • AU-descriptor: will match Australian image descriptors

For more advanced keyword search options, refer to the Advanced keywords options section of this guide.

For example

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?keyword_search=VC-01.11.04,AU-STAR+"
                
            

Multi-image search

For certain types of searches, it may be necessary to search more than one image, or more than one segment from a single image. In such cases, it is necessary to specify multiple segmentations, and which images they should apply to.

To accomplish this, the image_segments parameter can be used. The image_segments parameter is a JSON-formatted list of dictionaries, specifying each image and segmentation to be searched. Segmentation parameters may use either the left/right/upper/lower format, or the polygon format. For multi-image and multi-segment searches, the images must be already registered on the system, either by the segment route, or by previous searches.

To perform a multi-image search with a pentagon segment on image 831, and a square segment on image 832, the image_segments parameter might be: [{"image_id": "831", "polygon": [[20, 20], [40, 20], [45, 30], [30, 40], [15, 30]]}, {"image_id": "832", "left": 50, "right": 80, "upper": 80, "lower": 50}]

For searching multiple segments from the same image, simply specify the same image_id with each segment, such as: [{"image_id": "831", ...}, {"image_id": "831", ...}]

Note: As the JSON-formatted dictionary keys must be specified in double quotes, the image_segments parameter and value must be encased in single quotes if entering via the command line.

Note: The image_segments parameter was previously called image_boxes. This deprecated parameter name may still be used, and is identical in format to image_segments.

For example:

                
curl -F 'image_segments=[{"image_id": "831", "polygon": [[20, 20], [40, 20], [45, 30], [30, 40], [15, 30]]}, {"image_id": "832", "left": 50, "right": 80, "upper": 80, "lower": 50}]'
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"
     /api/v4/search/
                
            

Search options

The TrademarkVision's search API allows you to fine tune your searches to get the results in your preferred format and order. The following search options are available:

  • Pagination
  • Keywords and threshold fields
  • Advanced keyword options
  • Combination Operators
  • Trademark fields selection
  • Faceting
  • Web results
  • Image matching algorithms
  • Advanced text search

 

 

 

Pagination

Using results_per_page, you can easily specify how many results you would like to see in one page. The page parameters allows you to request results for a specific page.

You can specify an existing search id with search_id or append results_per_page and page to any new search query.

For example

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12743&results_per_page=10&page=0"
                
            

Will return 10 results from the first page of results.

Image quality

The quality of searched images can have a significant impact on search performance. To ensure that search results are high quality, the system will reject images of poor quality.

To bypass this check, and segment or search low quality images, simply ignore_quality=1.

Ignore image quality when segmenting:

                
curl -F "file=@/home/user/hello.jpg"
     -F "ignore_quality=1"
     -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     /api/v4/segment/
                
            

Ignore image quality when searching:

                
curl -F "file=@/home/user/hello.jpg"
     -F "ignore_quality=1"
     -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     /api/v4/search/
                
            

Object recognition and image reranking

TrademarkVision's API uses image comparison thresholds while searching for results similar to any uploaded image. To return such values, along with suggested keywords or image codes, you can add suggestions=1

Additionally, in your query, you can also modify the suggested keywords with the image codes or descriptors requested for object recognition (image reranking). If you would like to not use keywords in object recognition phase, simply include the following in your search query:

suggested_keyword_search=none

The following example illustrates the structure of the suggested keywords:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12743&suggestions=1"
                
            

Will return the following

                
{
    ...
    "suggested_keywords": {
        "VC": ["05.07.13", "05.07.22"]
    }
    ...
}
                
            

Using defined keywords for object recognition while running a search:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12743&suggested_keyword_search=VC-05.07.13,VC-05.07.22,VC-05.07.26"
                
            

Advanced keyword options

Keyword Search in our system refers to the codes or descriptors each Trademark office uses to describe and index its images (for instance, Vienna Codes, US Design Codes, AU image constituents). The keywords to search can be specified in any of a number of ways.

  1. They may be specified naked (eg. "05.07.01"), in which case that keyword will be searched in all datasets wherein it exists, within the scope of the search.
  2. They may include a "keyword standard" specifier (eg "US-05.07.01"), in which case the keyword will be searched in all datasets within the scope of the search which use that keyword standard.

These methods may also be mixed. For example:

keyword_search=US-05.07.05,VC-05.07.13,01.01.01

Will search for apples in countries using the US keyword standard, using the code 05.07.05, and it will also search for apples in countries using the VC keyword standard which uses a different code: 05.07.13.

Finally, it will also search all standards for the code 01.01.01, which happens to be roughly "Stars" in both US and VC. Independently of which of these methods you use, if the country you are searching has a hierarchy based system (i.e. VC and US) you can specify a precise level in the hierarchy to search by adding parameter "keyword_fields".

Additionally, since different countries have different systems, you can optionally specify the type of keyword to search by prepending the coding type followed with a dash, for instance "VC-05.07.22,US-05.07.33". By default, if no types are specified, the API will match it against the keywords in the datasets searched.

The keyword_fields parameter can be set to any combination of:

  • vc_category
  • vc_division
  • vc_section
  • keywords
                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12743&keyword_fields=vc_category,vc_division&keyword_search=05.01.02"
                
            

Will return trademarks with keywords included in 05.xx.yy and 05.01.yy

Combination operators

When combining image searching with text or keywords, we offer several options for the combination of results:

  • AND: Intersection of text or keyword search and image similarity search.
  • OR: Union of text or keyword search and image similarity search.
  • RERANK: Uses text or keyword search as the basis to retrieve results, and re-ranks (i.e. re-orders) the trademark results based on image similarity if it exists.
  • SMART_AND: Always pre-pending exact image similarity matches (i.e. with similarity values > 0.75) to the front of the results from AND operator, regardless of whether it matched against any text or keyword searching.
  • SMART_RERANK: Always pre-pending exact image similarity matches (i.e. with similarity values > 0.75) to the front of the results from RERANK operator, regardless of whether it matched against any text or keyword searching.

The operator can be varied via parameter "comb_op". By default, the API uses SMART_RERANK if no comb_op is specified. On TrademarkVision, we use SMART_RERANK by default.s.

If you wish to change the default operator, comb_op must be used as a search parameter:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12743&comb_op=SMART_RERANK"
                
            

Available trademark fields

You can control the fields returned for each result using the result_fields parameter. By the defaults, results will include the following fields:

  • tm_id
  • similarity
  • rank
  • dataset

In addition to the defaults fields, you can specify any combination of:

  • mardesc
  • keywords
  • vc_category
  • vc_division
  • vc_section
  • classes
  • owner
  • regions
  • status
  • status_detail
  • mark_type
  • mark_type_detail
  • image_url
  • image_thumb_url
  • st13

The following request will only Trademark ID, Owner and Nice classification:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12743&result_fields=tm_id,owner,classes"
                
            

Faceting

The TrademarkVision API allows you to facet results on the following trademark fields:

  • classes
  • status
  • status_detail
  • mark_type
  • mark_type_detail
  • keywords
  • vc_category
  • vc_division
  • vc_section

To add facets to the response, simple add the facets fields to your request, as following:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12743&facets=vc_section"
                
            

And the results will include the following data:

                
{
    ...
    "tmv": {
        "facets": {
            "vc_section": {
            "01.15.15": 223,
            "01.15.21": 47,
            "29.01.04": 155,
            "29.01.08": 61
            }
        }
    }
    ...
}
                
            

Adding web results

TrademarkVision can search Google Images and return web results that match the uploaded image. To see web results, add the web_image_search POST parameter when searching.

The following example shows how to return web results:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     -F "web_image_search=true"
     "/api/v4/search/"
                
            

This will generate the following response:

                
{
    "status": "Success",
    "image_id": 549,
    "tmv": { ... }
    "google": {
        "status":"OK",
        "results": [
            {
                "webimage_id": 111,
                "source_url": "/trademark.vision/example",
                "image_url": "/trademark.vision/example/image-1.png"
            },
            {
                "webimage_id": 140,
                "source_url": "/trademark.vision/example",
                "image_url": "/trademark.vision/example/image-2.png"
            },
            ...
        ]
    }
}
                
            

Image matching algorithms

By default, the API searches using a combination of algorithms. To specify the Colour image match algorithm, use the algorithms parameter.

Note that Coloursearches trademarks specifically registered for 'colour' protection, rather than the entire set of image trademarks. We recommend searching Colour by itself to avoid confusion.

To search for Colour trademarks, add algorithms=Colour to your search query

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     -F "image_id=549"
     "/api/v4/search/?algorithms=Colour"
                
            

And the results will include the following data:

                
{
    ...
    "tmv": {
        "facets": {
            "vc_section": {
            "01.15.15": 223,
            "01.15.21": 47,
            "29.01.04": 155,
            "29.01.08": 61
            }
        }
    }
    ...
}
                
            

Advanced text search

Text search supports wildcards, fuzzy and phonetic searches.

The following wildcards are available:

  • *: which will match zero to many characters
  • ?: which will match zero or one character

Fuzzy searches can be performed by adding text_search_type=Fuzzy to your search parameters or by appending ~N to each search term, where N is the desired distance. For example:

the quikc~1 bron~1 fos~1

Will find trademarks with any one-letter variation of those terms, including the quick brown fox.

Note: when setting the text_search_type parameter, we default fuzzy distance to ~2.

Phonetic search are executed by adding text_search_type=Phonetic to your text search. Phonetic searches use the 774-737-9330 algorithm.

For example

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?text_search=quikc bronw fos&text_search_type=Fuzzy"
                
            
                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?text_search=busy&text_search_type=Phonetic"
                
            

Image rotation

Sometimes a trademark may exist which is visually similar to the input image, but may have a different orientation. That is, it is similar to a rotated version of the input image.

To find such trademarks, the rotation_step_degrees parameter can be used.

This parameter defines the step size in degrees which the image will be compared at. For example, if rotation_step_degres=90, then the input image will be searched at rotations 0, 90, 180, and 270. For rotation_step_degrees=100, image rotations 0, 100, 200, 300 would be searched.

For example

                
curl -F "image_id=831"
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"
     -F "rotation_step_degrees=45"
     /api/v4/search/
                
            

will retrieve trademarks similar to the input image, rotated by angles 0, 45, 90, 135, 180, 225, 270, 315.

Search snapshots

The data in the TrademarkVision search system is constantly being updated. Additionally, the system undergoes periodic performance updates, to make it more accurate. This means that re-running an existing search may give slightly different results. If you wish to record exactly what the results were at a specific time, you can take a snapshot of a search.

 

 

 

Creating a snapshot

To save search results and create a new snapshot, include parameter snapshot_results=N, where N is the number of results to be saved in the snapshot. A snapshot ID, which can be used to retrieve this search snapshot, will be returned in the response.

For example:

                
curl -F "file=@/home/user/hello.jpg"
     -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     -F "snapshot_results=100"
     /api/v4/search/
                
            

On success, the response should include an ID for this snapshot:

                
{
    ...
    "tmv": {
        "snapshot_id": "6e28af2b-5435-4b81-8f01-742583f064ad",
		...
    },
    ...
}
                
            

Retrieving a snapshot

To retrieve the saved results, simply include the snapshot ID in the search parameters. For example:

snapshot_id=6e28af2b-5435-4b81-8f01-742583f064ad

This search can accept parameters result_fields and results_per_page; however, other search options will not be effective as the results have been generated from previous search.

To retrieve saved results:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     -F "snapshot_id=6e28af2b-5435-4b81-8f01-742583f064ad"
     /api/v4/search/
                
            

Listing available snapshots

To list all the snapshots saved under a user account, set snapshot_id=all

Each item in the list includes:

  • date: the date of the snapshot created
  • search: the search ID, which can be used to re-run the same search with parameter search. For example:

    search=d0429527-8b34-48b6-9393-2ac14cb0aa20

  • snapshot: the snapshot ID

To list all saved snapshots:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     -F "snapshot_id=all"
     /api/v4/search/
                
            

Returns:

                
{
    "all_snapshots": [
        {
            "date": "2017-11-29 04:34:44",
            "search": "d0429527-8b34-48b6-9393-2ac14cb0aa20",
            "snapshot": "6e28af2b-5435-4b81-8f01-742583f064ad"
        }
    ],
    "total_snapshots": 1
}
                
            

Result filters

TrademarkVision support filtering on various trademark data fields. You can add any combination of filters to your searches.

 

 

 

 

Datasets and regions

The datasets filter specifies which dataset the API should search into. As some datasets include multiple regions, like in the case of Internation Registrations, you can supply an additional regions parameters to specify which region you wish to include in your results.

TrademarkVision currently supports the following datasets:

  • TCM_CH: Switzerland (Thomson CompuMark)
  • TCM_CA: Canada (Thomson CompuMark)
  • TCM_PL: Poland (Thomson CompuMark)
  • TCM_AT: Austria (Thomson CompuMark)
  • TCM_AU: Australia (Thomson CompuMark)
  • TCM_NO: Norway (Thomson CompuMark)
  • TCM_JP: Japan (Thomson CompuMark)
  • TCM_SM: San Marino (Thomson CompuMark)
  • TCM_DU: Germany (Thomson CompuMark)
  • TCM_SP: Spain (Thomson CompuMark)
  • TCM_LT: Lithuania (Thomson CompuMark)
  • TCM_LV: Latvia (Thomson CompuMark)
  • TCM_DK: Denmark (Thomson CompuMark)
  • TCM_SK: Slovak Republic (Thomson CompuMark)
  • TCM_TR: Turkey (Thomson CompuMark)
  • TCM_HU: Hungary (Thomson CompuMark)
  • TCM_BG: Bulgaria (Thomson CompuMark)
  • TCM_FI: Finland (Thomson CompuMark)
  • TCM_BX: Benelux (Thomson CompuMark)
  • TCM_SE: Sweden (Thomson CompuMark)
  • TCM_BR: Brazil (Thomson CompuMark)
  • TCM_AR: Argentina (Thomson CompuMark)
  • TCM_HR: Croatia (Thomson CompuMark)
  • TCM_PT: Portugal (Thomson CompuMark)
  • TCM_KR: South Korea (Thomson CompuMark)
  • TCM_CZ: Czech Republic (Thomson CompuMark)
  • TCM_WO: World (Thomson CompuMark)
  • TCM_RU: Russian Federation (Thomson CompuMark)
  • TCM_IE: Ireland (Thomson CompuMark)
  • TCM_UF: United States (Thomson CompuMark)
  • TCM_EM: Europe (Thomson CompuMark)
  • TCM_MX: Mexico (Thomson CompuMark)
  • TCM_IS: Iceland (Thomson CompuMark)
  • TCM_GB: Great Britian (Thomson CompuMark)
  • TCM_EE: Estonia (Thomson CompuMark)
  • TCM_IT: Italy (Thomson CompuMark)
  • TCM_FR: France (Thomson CompuMark)

To apply the datasets and regions filter, simply add the datasets parameter to your search request, and only search the Australia, United States and France datasets:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12745&datasets=AU,US,FR"
                
            

If you wish to combine the datasets and regions filter, to return only Australian trademarks from the Australian and WIPO datasets:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12745&datasets=AU,WIPO&regions=AU"
                
            

The full list of datasets to search is currently:

              
"datasets=TCM_CH,TCM_CA,TCM_PL,TCM_AT,TCM_AU,TCM_NO,TCM_JP,TCM_SM,TCM_DU,TCM_SP,TCM_LT,TCM_LV,TCM_DK,TCM_SK,TCM_TR,TCM_HU,TCM_BG,TCM_FI,TCM_BX,TCM_SE,TCM_BR,TCM_AR,TCM_HR,TCM_PT,TCM_KR,TCM_CZ,TCM_WO,TCM_RU,TCM_IE,TCM_UF,TCM_EM,TCM_MX,TCM_IS,TCM_GB,TCM_EE,TCM_IT,TCM_FR"
              
            

Trademark classificiation

You can specify a list of Nice classes to filter your results based off their Nice classification.

Simply add classes to your search query:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12745&classes=1,3,41"
                
            

Trademark owner

The owner filter allows you to find trademarks owned by a specific entity. This field supports boolean logic and can be used in the following ways:

Mark AND Louis

To find all trademarks owned by both Mark AND Louis

Mark OR Louis

To find all trademarks owned by either Mark OR Louis

Simply add owner to your search query:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12745&owner=\"Mark AND Louis\""
                
            

Trademark goods and services

The goods_and_services filter allows to filter by trademark Goods and Services. You can use this field in combination with any boolean operator to narrow or expand your results:

medical OR devices

To find all trademarks that contain the terms medical or devices in their goods and services description

medical AND devices

To find all trademarks that contain medical and devices in their goods and services description

medical AND NOT devices

To find all trademarks that contain medical and not devices in their goods and services description

Simply add goods_and_services to your search query:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12745&goods_and_services=medical AND devices"
                
            

Trademark date

You can use the date_from and date_to filters to filter your result by Filing date. These fields are inclusive, and the date format is YYYYMMDD.

Find all applications after July 11 2011:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12745&date_from=20110711"
                
            

Find all applications before January 21 2016:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12745&date_to=20160121"
                
            

Find all applications between July 11 2011 and January 21 2016:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12745&date_from=20160121&date_to=20110711"
                
            

Trademark status

TrademarkVision allows you to filter by Live or Dead trademarks. In addition to this simple status filter, you can use the status_detail parameter to narrow your results by country specific statuses.

You can find all Live trademarks:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12745&status=Live"
                
            

Or all Pending trademarks in Australia:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12745&dataset=AU&status_detail=Pending"
                
            

Trademark type

If you are looking for a specific type of trademark, you can use the mark_type and mark_type_detail parameters to narrow your result set.

mark_type can have the following values:

  • Word
  • Figurative
  • Colour
  • Sound
  • Olfactory
  • Hologram
  • 3-D
  • Other

mark_type_details is dataset specific.

If you are looking for all Sound or Colour trademarks that match a specific search, you could add the following:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12745&mark_type=sound,colour"
                
            

Other filters

You can filter your resultset to only include results above a specified similarity threshold. Use the similarity_min parameter to adjust the threshold value.

Only include results with a minimum similarity of 0.35:

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/search/?search_id=12745&similarity_min=0.35"
                
            

Error handling

If your requests fail, the response will include one of the following API errors.

Authorisation & authentication errors

  • 700: Not authorised for the requested operation - message will vary depending on error
    • Account expired
    • Account not yet activated
    • No searches remaining
    • Your package does not grant access to the requested region(s)
  • 701: Not authenticated - message will vary depending on error
    • Login required for search. Please login first.
    • Your user/token pair did not pass authentication
    • Must include 'user' and 'token' parameters

Segmentation errors

  • 601: Missing file parameter
  • 602: Invalid search image post
  • 603: Unable to open image
  • 604: Unable to process image segmentation
  • 605: Image is too small. It should have width and height greater than 100px
  • 606: Unable to check image quality

Search errors

  • 620: Unanticipated API search error
  • 621: Error in parsing search request
  • 622: Search object creation error - message may vary depending on error
    • Selected a dataset that did not exist or is not supported
    • Attempted to access search that did not belong to this account
    • Unable to find search
    • Invalid search
    • Search requires either a text or image query; neither were provided
    • Search requires either a text or image query; text query could not be executed because none of the selected datasets support (those) keywords
    • Selected previous image does not exist
    • Unable to open image file
    • Image is too small. It should have width and height greater than 100px
    • Unable to check image quality
  • 623: Search error - message may vary depending on error
  • 624: Version not handled

Web Search errors

  • 641: Message may vary depending on error

Errors will be in the following format

                
{
    "err_code": 605,
    "status": "Image is too small...",
    "success": false
}
                
            

Status check

The API allows you to check the status of our servers. These routes are authenticated.

Test your connectivity to our servers using the noop operation

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/noop/"
                
            

Test server status with the status operation

                
curl -F "user=12345"
     -F "token=2uy-420a8efff7f882afc20d"
     "/api/v4/status/"
                
            

Migrate from v3

If you have integrated with our API v3, we recommend you upgrade to v4.

result_fields has changed its default settings, for performance improvement. Please not that in v3, most of the optional fields were set as default. We recommend you specify all the fields you would like to receive in your response.

algorithms has changed as we have introduced new algorithms. We recommend setting this value to all unless searching for Colour trademarks.

In v4, result_fields defaults to:

tm_id, similarity, rank, dataset

And has optional values:

mardesc, keywords, vc_category, vc_division, vc_section, classes,
owner, regions, status, status_detail, mark_type,mark_type_detail
image_url, image_thumb_url

in v3, the default values were:

tm_id, similarity, rank, dataset, keywords, vc_category, vc_division,
vc_section, classes, owner, status, status_detail,
mark_type, mark_type_detail

and optional values:

mardesc, regions, image_url, image_thumb_url

 

In v4, algorithm defaults to:

Texture, Shape, Parts, Parts2

In v3, it used to be

Texture, Shape

In both v3 and v4, it can be optionally set to

Colour

 

Summary

Summary of the API routes

Authentication routes

  • /api/v4/login
  • /api/v4/verify_token

Search and segmentation

  • /api/v4/search
  • /api/v4/segment

Status check routes

  • /api/v4/noop
  • /api/v4/status