TrademarkVision is a visual image search engine, primarily for trademarks and web search.

This API enables third-parties to utilize TrademarkVision functionality. For API access, please contact us.

• Examples
• Authentication
• Simple Image Search
• Image Segmentation + Image Search
• Search Options
• Filters
• Available Result Fields
• Error Codes
• Status Check
• Migrate from V2

• Search
• Segment

Obtaining a Token

To use the API, a token must first be obtained.

You can obtain a token for a specific user by sending a POST request with a username and password parameter to the /api/v3/login/ view. Using curl, the request would look like:

curl -d "username=jpulgarin&password=GGGGGG" SERVER_URL/api/v3/login/ 

If the request is successful, you will receive a JSON response like so:

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

An invalid username and password pair will produce a response like so:

{"success": false, "errors": "Unable to log you in, please try again"} 

You should store the user and token that are returned on the client accessing the API, as all subsequent calls will require that the request have a valid token and user pair.

Verifying a Token

You can verify that a token matches a given user by sending a GET request to the /api/v3/verify_token/ view, and sending the token and user as part of the URL. Using curl:

curl SERVER_URL/api/v3/verify_token/token/user
curl SERVER_URL/api/v3/verify_token/2uy-420a8efff7f882afc20d/32

If valid, you will receive the following JSON response:

{"success": true}

Using a Token

The client can access any API compatible view by sending a request to it, and including user and token as request parameters (either GET or POST). 

For the easiest case, where the image contains only a single object, the image can be sent via POST to the /api/v3/search/ view to search against both CeeqTM (trademarks) and Google Image Search (web).

Image Parameters are one of:

• "file": an image file; or
• "image_id": image id of a previously uploaded search image; or
• "image_ref": a referenced trademark of the format: ds-tm_id, where ds=EU|US|AU eg US-1234123; or
• "image_url": a http/https request for a logo on the public internet.

In addition, you can always add text_search to any image search.

• "text_search": text string can be a word mark.
• "text_search_type": Standard (default) | Fuzzy | Phonetic
• "keyword_search": comma-separated list of keywords (e.g. vienna codes, US design codes, AU image constituents). Can also be partial codes in the VC category, division, section heirarchy (e.g. "02" or "02.01" or "02.01.01")

Using curl it would look like:

curl SERVER_URL/api/v3/search/ -F "file=@/my/img/file.jpg" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Results are returned under "tmv". Within this object there is a link back to the search results page (search_url), and a list of results. Each item in the includes an image url (image_url) and a webpage url (source_url). This is an example JSON response:

{"status": "Success", 
 "image_id": 549,
 "tmv": 
  {"search_url": "SERVER_URL/lm/search/?search_id=2649", 
   "search_id": 2649,
   "total_results": 110,
   "results":  [
      {"tm_id": "1595276",
       "rank": 1,
       "similarity": 0.92,
       "keywords": ["ANIMAL", "CAT", "SILHOUETTE"],
       "dataset": "AU",
       "owner": "iCAT Co",
       "status_detail": "Registered/Protected"
      },
    …]
  }
}

On error, you will receive the a JSON response with an error message in status:

{"status": "Selected previous image does not exist"}

For the case where the images contain more than one object (for instance, a logo with text beside it), the image can be sent for logo segmentation first. The image can be sent via POST to the /api/v3/segment/ view. Using curl it would look like:

curl SERVER_URL/api/v3/segment/ -F "file=@/my/img/file.jpg" -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

If valid, you will receive a JSON response with the image id and segments:

{"image_str": "(831) search_image/cpa_5.jpeg", 
 "image_id": 831, 
 "image_h": 114, 
 "image_w": 443,
 "invert": False,
 "segments": [
  {"id": 2317, "segment_type": "device", "word": "", "right": 112, "lower": 110, "left": 4, "upper": 4, "is_selected": true}, 
  {"id": 2318, "segment_type": "word", "word": "CPA", "right": 228, "lower": 74, "left": 133, "upper": 39, "is_selected": false}
 ]
}

Each "segment" has information pertaining to whether it is a logo "segment_type":"device", or a word "segment_type":"word", it also has the box ("upper","left","lower","right") in reference to the original image, "is_selected" is the flag to indicate 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/v3/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".

Using curl it would look like:

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

The results returned are the same as described in the previous section.

Alternatively, if you supply the auto_segment parameter to the search request, our system will attempt to automatically detect which segment is the relevant image segment, and search that in addition to the supplied image. For the CURL example, only the presence of the auto_segment parameter is needed. In an HTML form, it can be implement as a field (for instance, a checkbox to turn the option on or off).

curl SERVER_URL/api/v3/search/ -F "image_id=831" \
-F "auto_segment=" -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Results per page and Pagination

By default, the Top 40 results are returned. You can access up to Top 1000 results.
The number of results per page is controlled by a parameter appended to the url: ?results_per_page=10
The page number can be controlled by the parameter: &page=0
Use the search_id returned in the original result for faster cached result pagination.

Using curl it would look like this to get the first 3 pages of 10 results each:

curl "SERVER_URL/api/v3/search/?search_id=12743&results_per_page=10&page=0" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

curl "SERVER_URL/api/v3/search/?search_id=12743&results_per_page=10&page=1" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

curl "SERVER_URL/api/v3/search/?search_id=12743&results_per_page=10&page=2" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Advanced Thresholding and Keyword Suggestions

A parameter called "suggestions" can be set to "true" or "1" to return a recommended threshold list for exact and similar image matches and keyword_suggestions related to those similar images.

Example:

curl "SERVER_URL/api/v3/search/?search_id=12743&results_per_page=10&page=0&suggestions=1" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

The response has two extra items "thresholds" and "suggested_keywords" which are dictionaries like this:

{...
 "thresholds": {"similar": 0.25, "exact": 0.75}
 "suggested_keywords": {"VC": ["05.07.13", "05.07.22"]},
}

Choosing Image Matching Algorithms

To specify which image match algorithm you wish to use, use the algorithms parameter. If you don't specify this parameter the system will default to a combination of Texture and Shape. Currently the complete list of available algorithms is: Texture, Shape, and Colour.

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

"algorithms": Texture,Shape
"algorithms": Colour

curl "SERVER_URL/api/v3/search/?algorithms=Texture,Shape" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Fine tuning Keyword Search

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 heirarchy based system (i.e. VC and US) you can specify a precise level in the heirarchy to search by adding parameter "keyword_fields".

Possible options are "vc_category", "vc_division", "vc_section", "keywords" (keywords maps to the raw data provided from the office and often the same as vc_section). keyword_fields options can be passed as a comma-separated list.

By default (if no keyword_fields are specified), all of those fields are included.

"keyword_fields": vc_category,vc_division,vc_section,keywords

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, we will match it against the keywords in the datasets searched.

curl "SERVER_URL/api/v3/search/?keyword_search=05.07.13&keyword_fields=vc_section" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

curl "SERVER_URL/api/v3/search/?keyword_search=VC-05.07.13&keyword_fields=vc_section" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Choosing Image and Text/Keyword Combination Operators

When combining and a search image (using image recognition) with text or keyword search (using text search), we offer several options for how the results get combined:

"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.

curl "SERVER_URL/api/v3/search/?comb_op=SMART_RERANK&keyword_search=05.07.13&keyword_fields=vc_section" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

You may narrow your search by applying filters to certain fields. The supported fields, and how to filter by them, is described below.

By default, when multiple terms are supplied for a filter, results need only match one of the supplied terms (logical OR). If you wish to only see documents that match all of your supplied terms (logical AND), include "+" as an additional term, like so:

"classes": +,3,12

The above filter will only match documents with classes 3 and 12

Filter by Dataset

To specify which datasets you wish to search, use the datasets parameter. If you don't specify this parameter the system will search those enabled for your account. We recommend that you specify this parameter.

"datasets": TCM_AA,TCM_AAPL,TCM_AB,TCM_AD,TCM_AE,TCM_AF,TCM_AG,TCM_AI,TCM_AL,TCM_AM,TCM_AO,TCM_AR,TCM_AT,TCM_AU,TCM_AZ,TCM_BA,TCM_BB,TCM_BD,TCM_BG,TCM_BH,TCM_BI,TCM_BM,TCM_BN,TCM_BO,TCM_BQ,TCM_BR,TCM_BS,TCM_BT,TCM_BW,TCM_BX,TCM_BY,TCM_BZ,TCM_CA,TCM_CH,TCM_CL,TCM_CN,TCM_CO,TCM_CR,TCM_CU,TCM_CV,TCM_CW,TCM_CY,TCM_CZ,TCM_DJ,TCM_DK,TCM_DM,TCM_DO,TCM_DOMS,TCM_DU,TCM_DZ,TCM_EC,TCM_EE,TCM_EG,TCM_EM,TCM_ET,TCM_FI,TCM_FJ,TCM_FR,TCM_GB,TCM_GCNS,TCM_GD,TCM_GE,TCM_GG,TCM_GH,TCM_GI,TCM_GM,TCM_GOOG,TCM_GR,TCM_GT,TCM_GY,TCM_HK,TCM_HN,TCM_HR,TCM_HT,TCM_HU,TCM_ID,TCM_IE,TCM_IL,TCM_IN,TCM_IQ,TCM_IR,TCM_IS,TCM_IT,TCM_JE,TCM_JM,TCM_JO,TCM_JP,TCM_KE,TCM_KG,TCM_KH,TCM_KN,TCM_KR,TCM_KU,TCM_KW,TCM_KY,TCM_KZ,TCM_LA,TCM_LB,TCM_LC,TCM_LI,TCM_LK,TCM_LR,TCM_LS,TCM_LT,TCM_LV,TCM_LY,TCM_MA,TCM_MC,TCM_MD,TCM_ME,TCM_MG,TCM_MK,TCM_MM,TCM_MN,TCM_MO,TCM_MS,TCM_MT,TCM_MU,TCM_MV,TCM_MW,TCM_MX,TCM_MY,TCM_MZ,TCM_NA,TCM_NG,TCM_NI,TCM_NO,TCM_NP,TCM_NZ,TCM_OA,TCM_OM,TCM_PA,TCM_PE,TCM_PG,TCM_PH,TCM_PK,TCM_PL,TCM_PSGZ,TCM_PSWB,TCM_PT,TCM_PY,TCM_QA,TCM_RO,TCM_RS,TCM_RU,TCM_RW,TCM_SA,TCM_SB,TCM_SC,TCM_SD,TCM_SE,TCM_SG,TCM_SI,TCM_SK,TCM_SL,TCM_SM,TCM_SP,TCM_SR,TCM_ST,TCM_STER,TCM_SV,TCM_SX,TCM_SY,TCM_SZ,TCM_TC,TCM_TH,TCM_TI,TCM_TJ,TCM_TM,TCM_TN,TCM_TO,TCM_TR,TCM_TT,TCM_TW,TCM_TZ,TCM_UA,TCM_UF,TCM_UG,TCM_USST,TCM_UY,TCM_UZ,TCM_VC,TCM_VE,TCM_VG,TCM_VN,TCM_WATCH,TCM_WO,TCM_WS,TCM_XA,TCM_XK,TCM_YE,TCM_ZA,TCM_ZM,TCM_ZR,TCM_ZW,TCM_ZZ

Currently the complete list of available datasets is:

"TCM_AA": Aripo (CompuMark)
"TCM_AAPL": Apple AppStore
"TCM_AB": Aruba (CompuMark)
"TCM_AD": Andorra (CompuMark)
"TCM_AE": United Arab Emirates (CompuMark)
"TCM_AF": Afghanistan (CompuMark)
"TCM_AG": Antigua and Barbuda (CompuMark)
"TCM_AI": Anguilla (CompuMark)
"TCM_AL": Albania (CompuMark)
"TCM_AM": Armenia (CompuMark)
"TCM_AO": Angola (CompuMark)
"TCM_AR": Argentina (CompuMark)
"TCM_AT": Austria (CompuMark)
"TCM_AU": Australia (CompuMark)
"TCM_AZ": Azerbaijan (CompuMark)
"TCM_BA": Bosnia-Herzegovina (CompuMark)
"TCM_BB": Barbados (CompuMark)
"TCM_BD": Bangladesh (CompuMark)
"TCM_BG": Bulgaria (CompuMark)
"TCM_BH": Bahrain (CompuMark)
"TCM_BI": Burundi (CompuMark)
"TCM_BM": Bermuda (CompuMark)
"TCM_BN": Brunei Darussalam (CompuMark)
"TCM_BO": Bolivia (CompuMark)
"TCM_BQ": Bes Islands (Bonaire, Saint Eustatius and Saba) (CompuMark)
"TCM_BR": Brazil (CompuMark)
"TCM_BS": Bahamas (CompuMark)
"TCM_BT": Bhutan (CompuMark)
"TCM_BW": Botswana (CompuMark)
"TCM_BX": Benelux (CompuMark)
"TCM_BY": Belarus (CompuMark)
"TCM_BZ": Belize (CompuMark)
"TCM_CA": Canada (CompuMark)
"TCM_CH": Switzerland (CompuMark)
"TCM_CL": Chile (CompuMark)
"TCM_CN": China (CompuMark)
"TCM_CO": Colombia (CompuMark)
"TCM_CR": Costa Rica (CompuMark)
"TCM_CU": Cuba (CompuMark)
"TCM_CV": Cape Verde Islands (CompuMark)
"TCM_CW": Curacao (CompuMark)
"TCM_CY": Cyprus (CompuMark)
"TCM_CZ": Czech Republic (CompuMark)
"TCM_DJ": Djibouti (CompuMark)
"TCM_DK": Denmark (CompuMark)
"TCM_DM": Dominica (CompuMark)
"TCM_DO": Dominican Republic (CompuMark)
"TCM_DOMS": Domain Names
"TCM_DU": Germany (CompuMark)
"TCM_DZ": Algeria (CompuMark)
"TCM_EC": Ecuador (CompuMark)
"TCM_EE": Estonia (CompuMark)
"TCM_EG": Egypt (CompuMark)
"TCM_EM": Europe (CompuMark)
"TCM_ET": Ethiopia (CompuMark)
"TCM_FI": Finland (CompuMark)
"TCM_FJ": Fiji (CompuMark)
"TCM_FR": France (CompuMark)
"TCM_GB": Great Britain (CompuMark)
"TCM_GCNS": Global Company Names
"TCM_GD": Grenada (CompuMark)
"TCM_GE": Georgia (CompuMark)
"TCM_GG": Guernsey (CompuMark)
"TCM_GH": Ghana (CompuMark)
"TCM_GI": Gibraltar (CompuMark)
"TCM_GM": Gambia (CompuMark)
"TCM_GOOG": Google Playstore
"TCM_GR": Greece (CompuMark)
"TCM_GT": Guatemala (CompuMark)
"TCM_GY": Guyana (CompuMark)
"TCM_HK": Hong Kong (CompuMark)
"TCM_HN": Honduras (CompuMark)
"TCM_HR": Croatia (CompuMark)
"TCM_HT": Haiti (CompuMark)
"TCM_HU": Hungary (CompuMark)
"TCM_ID": Indonesia (CompuMark)
"TCM_IE": Ireland (CompuMark)
"TCM_IL": Israel (CompuMark)
"TCM_IN": India (CompuMark)
"TCM_IQ": Iraq (CompuMark)
"TCM_IR": Iran (CompuMark)
"TCM_IS": Iceland (CompuMark)
"TCM_IT": Italy (CompuMark)
"TCM_JE": Jersey (CompuMark)
"TCM_JM": Jamaica (CompuMark)
"TCM_JO": Jordan (CompuMark)
"TCM_JP": Japan (CompuMark)
"TCM_KE": Kenya (CompuMark)
"TCM_KG": Kyrgyztan (CompuMark)
"TCM_KH": Cambodia (CompuMark)
"TCM_KN": Saint Kitts and Nevis (CompuMark)
"TCM_KR": South Korea (CompuMark)
"TCM_KU": Kurdistan (CompuMark)
"TCM_KW": Kuwait (CompuMark)
"TCM_KY": Cayman Islands (CompuMark)
"TCM_KZ": Kazakhstan (CompuMark)
"TCM_LA": Laos (CompuMark)
"TCM_LB": Lebanon (CompuMark)
"TCM_LC": Saint Lucia (CompuMark)
"TCM_LI": Liechtenstein (CompuMark)
"TCM_LK": Sri Lanka (CompuMark)
"TCM_LR": Liberia (CompuMark)
"TCM_LS": Lesotho (CompuMark)
"TCM_LT": Lithuania (CompuMark)
"TCM_LV": Latvia (CompuMark)
"TCM_LY": Libya (CompuMark)
"TCM_MA": Morocco (CompuMark)
"TCM_MC": Monaco (CompuMark)
"TCM_MD": Moldova (CompuMark)
"TCM_ME": Montenegro (CompuMark)
"TCM_MG": Madagascar (CompuMark)
"TCM_MK": Macedonia (CompuMark)
"TCM_MM": Myanmar (CompuMark)
"TCM_MN": Mongolia (CompuMark)
"TCM_MO": Macao (CompuMark)
"TCM_MS": Montserrat (CompuMark)
"TCM_MT": Malta (CompuMark)
"TCM_MU": Mauritius (CompuMark)
"TCM_MV": Maldives (CompuMark)
"TCM_MW": Malawi (CompuMark)
"TCM_MX": Mexico (CompuMark)
"TCM_MY": Malaysia (CompuMark)
"TCM_MZ": Mozambique (CompuMark)
"TCM_NA": Namibia (CompuMark)
"TCM_NG": Nigeria (CompuMark)
"TCM_NI": Nicaragua (CompuMark)
"TCM_NO": Norway (CompuMark)
"TCM_NP": Nepal (CompuMark)
"TCM_NZ": New Zealand (CompuMark)
"TCM_OA": Oapi (CompuMark)
"TCM_OM": Oman (CompuMark)
"TCM_PA": Panama (CompuMark)
"TCM_PE": Peru (CompuMark)
"TCM_PG": Papua New Guinea (CompuMark)
"TCM_PH": Philippines (CompuMark)
"TCM_PK": Pakistan (CompuMark)
"TCM_PL": Poland (CompuMark)
"TCM_PSGZ": Gaza (CompuMark)
"TCM_PSWB": West Bank (CompuMark)
"TCM_PT": Portugal (CompuMark)
"TCM_PY": Paraguay (CompuMark)
"TCM_QA": Qatar (CompuMark)
"TCM_RO": Romania (CompuMark)
"TCM_RS": Serbia (CompuMark)
"TCM_RU": Russian Federation (CompuMark)
"TCM_RW": Rwanda (CompuMark)
"TCM_SA": Saudi Arabia (CompuMark)
"TCM_SB": Solomon Islands (CompuMark)
"TCM_SC": Seychelles (CompuMark)
"TCM_SD": Sudan (CompuMark)
"TCM_SE": Sweden (CompuMark)
"TCM_SG": Singapore (CompuMark)
"TCM_SI": Slovenia (CompuMark)
"TCM_SK": Slovak Republic (CompuMark)
"TCM_SL": Sierra Leone (CompuMark)
"TCM_SM": San Marino (CompuMark)
"TCM_SP": Spain (CompuMark)
"TCM_SR": Suriname (CompuMark)
"TCM_ST": Sao Tome and Principe (CompuMark)
"TCM_STER": Article 6ter (CompuMark)
"TCM_SV": El Salvador (CompuMark)
"TCM_SX": Sint Maarten (CompuMark)
"TCM_SY": Syrian Arabic Republic (CompuMark)
"TCM_SZ": Swaziland (CompuMark)
"TCM_TC": Turks and Caicos Islands (CompuMark)
"TCM_TH": Thailand (CompuMark)
"TCM_TI": East Timor (CompuMark)
"TCM_TJ": Tajikistan (CompuMark)
"TCM_TM": Turkmenistan (CompuMark)
"TCM_TN": Tunisia (CompuMark)
"TCM_TO": Tonga (CompuMark)
"TCM_TR": Turkey (CompuMark)
"TCM_TT": Trinidad And Tobago (CompuMark)
"TCM_TW": Taiwan (CompuMark)
"TCM_TZ": United Republic Of Tanzania (CompuMark)
"TCM_UA": Ukraine (CompuMark)
"TCM_UF": United States (CompuMark)
"TCM_UG": Uganda (CompuMark)
"TCM_USST": U.S. State (CompuMark)
"TCM_UY": Uruguay (CompuMark)
"TCM_UZ": Uzbekistan (CompuMark)
"TCM_VC": Saint Vincent and the Grenadines (CompuMark)
"TCM_VE": Venezuela (CompuMark)
"TCM_VG": British Virgin Islands (CompuMark)
"TCM_VN": Vietnam (CompuMark)
"TCM_WATCH": Watch Data (CompuMark)
"TCM_WO": World (CompuMark)
"TCM_WS": Samoa (CompuMark)
"TCM_XA": Turkish Republic of Northern Cyprus (CompuMark)
"TCM_XK": Kosovo (CompuMark)
"TCM_YE": Yemen (CompuMark)
"TCM_ZA": South Africa (CompuMark)
"TCM_ZM": Zambia (CompuMark)
"TCM_ZR": Congo (Democratic Republic) (CompuMark)
"TCM_ZW": Zimbabwe (CompuMark)
"TCM_ZZ": Zanzibar (CompuMark)

curl "SERVER_URL/api/v3/search/?datasets=AU,US" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Filter by Region

Some datasets are international datasets, which include data from multiple regions. When searching such datasets, you may provide the additional filter parameter regions to restrict the results returned from these particular datasets to those from the regions you specified. The regions parameter is currently only available for use on the WIPO dataset.

"regions": FR,NZ

curl "SERVER_URL/api/v3/search/?regions=FR,NZ&datasets=FR,NZ,WIPO" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Filter by Nice class

To specify which classes you wish to search, use the classes parameter. If you don't specify this parameter the system will search all.

"classes": 1,2,.... You can specify which classes you want to search.

curl "SERVER_URL/api/v3/search/?classes=34,35" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Filter by Owner

To filter by owner, use owner parameter. The filter is not case sensitive and will do substring search by default.

"owner":"apple"

curl "SERVER_URL/api/v3/search/?owner=apple" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Filter by Date

If you would like to search by date range (defaults to Filing Date), you can use date_from and date_to. The format is YYYYMMDD. If you don't specify one, it's open-ended.

"date_from": 20141231 The from date inclusive
"date_to": 20150411 The to date inclusive

curl "SERVER_URL/api/v3/search/?date_from=20150130" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Filter by Status

By default, we return results of all statuses. If you want a specific status, use status filter. This is a comma separated list of allowed registation status.

"status": Live,Dead

curl "SERVER_URL/api/v3/search/?status=Live" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Filter by Detailed Status

By default, we return results of all statuses. To filter by country-specific status, use status_detail filter. This is a comma separated list of allowed registation status.

"status_detail": Registered,Pending See dataset specific documentation for the full set or send us an email.

curl "SERVER_URL/api/v3/search/?status_detail=Registered,Pending" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Filter by Mark Type

By default, we return results of all mark types. If you want specific types of marks, use mark_type filter. This is a comma separated list of allowed registation status.

"mark_type": Word,Figurative,Colour,Sound,Olfactory,Hologram,3-D,Other

curl "SERVER_URL/api/v3/search/?mark_type=Figurative" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Filter by Detailed Mark Type

By default, we return results of all mark types. To filter by country-specific mark type, use mark_type_detail filter. This is a comma separated list of allowed mark types.

"mark_type_detail": Figurative,Word See dataset specific documentation for the full set or send us an email.

curl "SERVER_URL/api/v3/search/?mark_type_detail=Figurative" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Filter by Similarity Minimum

This option will allow you to specify a minimum similarity. To do this use similarity_min filter. This is a value from 0 to 1.

"similarity_min": Minimum similarity to return.

curl "SERVER_URL/api/v3/search/?similarity_min=0.2" -F "image_id=549" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Adding web search

You can also search the web for images by adding the following optional parameter:
"web_image_search": true/false. If true, also run a search of the web for similar images(you must provided an image). Default is false.

Using curl it would look like:

curl SERVER_URL/api/v3/search/ -F "file=@/my/img/file.jpg" -F "web_image_search=true" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Here are some example results:

{"status": "Success", 
 "image_id": 549,
 "tmv": 
  { [ as described above ] 
  }
 "google": 
  {"status":"OK",
   "results": [
     {"webimage_id": 111,
      "source_url": "https://www.iconfinder.com/icons/2453/add_bookmark_icon",  
      "image_url": "https://cdn2.iconfinder.com/data/icons/picons-essentials/57/favorite_add-128.png"}, 
     {"webimage_id": 140,
      "source_url": "http://findicons.com/search/favourite-add", 
      "image_url": "http://png-5.findicons.com/files/icons/2315/default_icon/128/add_favourite.png"}, 
     …]}, 
}

Choosing the Result Fields

You can control the fields returned for each result using the result_fields parameter. By default this is set to:

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

mardesc,image_url,image_thumb_url,regions

Field notes: mardesc - contains the text component of the trademark.
dataset vs region - Most datasets correspond 1:1 with a region. However there are datasets that span multiple regions (such as WIPO), and when searching these datasets it may be of interest to know which countries the application concerns. In these situations, that information is available under the optional "regions" field.

Using curl to just get the tm_id and image_url would look like:

curl "SERVER_URL/api/v3/search/?search_id=12743&result_fields=tm_id,image_url" \
     -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

Request faceting data for certain fields

Sometimes it may be useful to know what values are most commonly found in certain fields within the domain of a given search. To this end we also include simple faceting functionality over a subset of the available fields. The fields currently eligible for faceting are:

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

Although this list may expand over time.
To request faceting, simply add the following parameter:
"facets": list,of,fields
Where the value is a comma-separated list of the fields you want faceted. Fields included that are not a part of the above list of eligible fields will be ignored.

Response format

{
    "image_id": 8728, 
    "status": "Success", 
    "tmv": {
        "facets": {
            "vc_section": {
                "01.15.15": 223,
                "01.15.21": 47,
                "24.03.07": 50,
                "25.01.94": 68,
                "26.01.03": 106,
                "26.04.01": 60,
                "26.04.02": 116,
                "26.04.05": 160,
                "26.04.22": 109,
                "26.04.24": 38,
                "26.11.01": 70,
                "26.11.13": 89,
                "26.11.99": 40,
                "26.99.03": 47,
                "27.05.01": 251,
                "27.05.21": 52,
                "29.01.01": 74,
                "29.01.03": 47,
                "29.01.04": 155,
                "29.01.08": 61
            }
        }, 
        "results": [as described above]
        "search_id": 17079, 
        "search_url": "http://trademark.vision/lm/search/?search_id=17079", 
        "total_results": 24738
    }
}

The layout of the "facets" as they are returned is as follows: within the "facets" object, each key corresponds to a fieldname you supplied in the request. The value stored under that key is an object containing the value:count pair for the top 20 most frequent values in that field within the scope of your search results.

Response format

{
    "err_code": 605,
    "status": "Image is too small. It should have width and height greater than 100px ",
    "success": false
}

Authorisation & authentication

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

Segment

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

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 Image Search

641 : < message may vary depending on error >

Noop

This will "ping" the server. (noop==No Operation). Basically just returns {"success":true}. Login is not required for this call.

curl SERVER_URL/api/v3/noop/

Status

Login is required. Not currently implemented.

curl SERVER_URL/api/v3/status/ -F "user=32" -F "token=2uy-420a8efff7f882afc20d"

The results object has changed slightly. Results under the ceeqtm field is now under the tmv field.

The field tm_id is now a string (was an int).

We no longer group the results by different class types (eg selected_classes). The results are moved directly under results.

So in v2, you might have referred to an element using:

    obj.ceeqtm.results.selected_classes[i]

So now this would be:

    obj.tmv.results[i]

The meaning of text_search has changed so that keyword codes (eg vienna codes or ATMOSS codes or US design codes) are now in keyword_search.

The results no longer return image_url and source_url by default. The returned field confidence is now called similarity.

The search_id and total_results fields are now returned from the search. Use the search_id returned in the original result for faster cached result pagination.

The old parameter dataset_group is now datasets.

We have exposed the following parameters to the API search owner, date_from, date_to, classes, status, status_detail, algorithms, similarity_min, result_fields, mark_type, mark_type_detail.

Query params are now available via HTTP GET. GET params override POST ones.