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.
Simple integration samples are also available in our examples.
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
}
TrademarkVision's simple search API can be used to search a trademark image against the TrademarkVision datasets. This is useful for testing purposes and when images only contain one device.
You can perform searches with:
In addition, you can filter your results by using any combination of trademark words and keywords or codes.
This example shows how to search using a new image.
curl -F "file=@/home/user/hello.jpg"
-F "user=12345"
-F "token=2uy-420a8efff7f882afc20d"
/api/v4/search/
On success, you will receive a search result set with some basic trademark information:
{
"status": "Success",
"image_id": 549,
"tmv": {
"search_url": "/lm/search/?search_id=2649",
"search_id": 2649,
"total_results": 110,
"results": [
{
"tm_id": "123456",
"rank": 1,
"similarity": 0.92,
"keywords": ["ANIMAL", "CAT", "SILHOUETTE"],
"dataset": "AU",
"owner": "Hello Pty Ltd",
"status_detail": "Registered/Protected"
}, ...
]
}
}
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/
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/
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:
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?"
The API supports direct keyword and codes search. This allows you to search for images using Vienna codes, US design codes 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:
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+"
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/
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:
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.
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/
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"
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.
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:
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
When combining image searching with text or keywords, we offer several options for the combination of results:
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"
You can control the fields returned for each result using the result_fields parameter. By the defaults, results will include the following fields:
In addition to the defaults fields, you can specify any combination of:
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"
The TrademarkVision API allows you to facet results on the following trademark fields:
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
}
}
}
...
}
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": "http://trademark.vision/example",
"image_url": "http://trademark.vision/example/image-1.png"
},
{
"webimage_id": 140,
"source_url": "http://trademark.vision/example",
"image_url": "http://trademark.vision/example/image-2.png"
},
...
]
}
}
This option will automatically add any text found in the image via optical character recognition (OCR) to the search.
Note: Using this parameter will change the combination operator to OR in order to boost results with the detected text.
The following request will add any detected text to the search:
curl -F "search_id=12745"
-F "user=12345"
-F "token=2uy-420a8efff7f882afc20d"
-F "ocr_text_search=true"
/api/v4/search/
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
}
}
}
...
}
Text search supports wildcards, fuzzy and phonetic searches.
The following wildcards are available:
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 NYSIIS 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"
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.
When significant portion of the image used for searching has coloured background, entire image is used for searching rather than searching with the best possible crop.
Using auto_trimrgb=1 flag with the search forces the api to trim the coloured background and search with the optimal crop
Note: Enabling this by default has some undesirable consequences.
For example
curl -F "image_id=831"
-F "user=32" -F "token=2uy-420a8efff7f882afc20d"
-F "auto_trimrgb=1"
/api/v4/search/
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.
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",
...
},
...
}
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/
To list all the snapshots saved under a user account, set snapshot_id=all
Each item in the list includes:
search=d0429527-8b34-48b6-9393-2ac14cb0aa20
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
}
TrademarkVision support filtering on various trademark data fields. You can add any combination of filters to your searches.
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:
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®ions=AU"
The full list of datasets to search is currently:
"datasets=MX"
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"
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\""
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"
You can use the date_from, date_to, and date_on 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"
Instead of searching for a date range, use the date_on filter when you need to filter based on a specific date.
curl -F "user=12345"
-F "token=2uy-420a8efff7f882afc20d"
"/api/v4/search/?search_id=12745&date_on=20110711"
You can use the appnum filter to narrow down your results by application numbers and the regnum filter to achieve the same for registration numbers. You have the flexibility to use one or both of these filters.
For example, using both:
curl -F "user=12345"
-F "token=2uy-420a8efff7f882afc20d"
"/api/v4/search/?search_id=12745&appnum=123456®num=123456"
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"
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:
mark_type_detail 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"
If you are looking for the results with a certain keyword/s, you can use the keywords_filter to narrow your results.
keywords_filter can have a list of values from the supported keyword standard for the datasets included in the results
Example: mark_type_details=SG-CHAINS,VC-26.04.02
If you are looking for marks that has either SG-CHAINS or VC-26.04.02, you can add the following
curl -F "user=12345"
-F "token=2uy-420a8efff7f882afc20d"
"/api/v4/search/?search_id=12745&keywords_filter=SG-CHAINS,VC-26.04.02"
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"
If your requests fail, the response will include one of the following API errors.
Authorisation & authentication errors
Segmentation errors
Search errors
Web Search errors
Errors will be in the following format
{
"err_code": 605,
"status": "Image is too small...",
"success": false
}
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/"
Summary of the API routes
Authentication routes
Search and segmentation
Status check routes