Getting started - General

  

1. What is the API endpoint to retrieve information about the database status?

The /v1/databaseStatus endpoint provides information about the freshness of the database. It includes the date of the most recent update to the database and a list of the most recent trademarks that have been added to the database.

2. What information does the database status endpoint return?

• Last update date
• Latest trademarks

3. How frequently is the database updated?

Trademark events are processed daily. New trademark filings are searchable after 2 days of filing.

4. What is the maximum number of results that can be returned?

For standard endpoints the maximum number of results returned is 250.

For batch calls the maximum number of results returned is 25,000.

5. How can I batch a trademark search?

You can batch a trademark search by using the specific batch endpoint, and you can retrieve up to 25 000 results.

6. What is the difference between a live/registered status and a dead/abandoned status?

A live/registered status indicates that the trademark is currently valid and in use. A dead/abandoned status indicates that the trademark is no longer valid and is not in use.

7. How can I get all the details of a trademark?

You can get all the details of a trademark by using the serial number endpoints.

8. What is the difference between a classification and a description?

A classification is a code that is used to categorize trademarks. A description is a text that provides more information about the trademark.

9. What does the term “classification” mean in the context of trademark search results?

Classification refers to the specific goods or services that the trademark is associated with. It is based on the US Patent and Trademark Office (USPTO) classification system. Each trademark can have multiple classifications.

10. How can I get the classification of a trademark?

You can get the classification of a trademark by using the serial number endpoints.

A brief example of the classification attribute returned:

 {
  "international_code_total_no": "1",
  "international_code": "008",
  "us_code_total_no": "3",
  "us_code": "",
  "status_code": "6",
  "first_use_anywhere_date": "2021-09-15",
  "first_use_in_commerce_date": "2021-09-15",
  "primary_code": "008"
 }
]

11. How can I get the renewal period for a trademark?

You can get the expiring date for a trademark by using the serial number endpoints, or the expiring endpoint.

12. Can I search for trademarks that should be renewed soon?

Yes, you can use the /v1/trademarkExpiring endpoint to search for trademarks where the projected renewal/expiration date is within a specified range. This endpoint allows you to identify trademarks that are approaching their renewal deadline.

13. Can I obtain the email of the trademark owners?

Yes, you can use the owner and serial number endpoints to retrieve the owner section and there the email migh be listed, but be aware this information is available only on records where it’s publicly disclosed. Not every trademark has this information.

14. Can you provide examples of each endpoint?

Each endpoint documentation has an example of how to prepare inputs and what output is returned. In case you want further discussion, reach out privately in Rapid Hub to the service support and they will be happy to answer your questions.

15. What is the expected latency of the service?

The typical latency of the service is less than 500 milliseconds, and the initial batch calls latency is around 2-10 seconds.

16. Are the designs retrievable?

This service doesn’t provide access to designs.

  

Serial Number and full trademark details retrieval

  

17. What is the API endpoint to do a serial number search?

/v1/serialSearch

18. What information does the serial number search return?

• Trademark name, keyword
• Serial number
• Status
• Owner(s)
• Address
• Classification
• Filing date
• Registration date
• Expiring date
• Statements
• Trademark events

19. What is the API endpoint to do a batch serial number search?

/v1/batchSerialSearch

20. What information does the batch serial number search return?

On batch call it’s configurable what fields are returned. Essentially all details can be returned about a trademark entry.

21. What is the difference between the /v1/serialSearch and /v1/batchSerialSearch endpoints?

• /v1/serialSearch performs a search based on a trademark’s serial number and returns detailed information about the trademark, including its description, owners, and status history.

• /v1/batchSerialSearch allows you to search for multiple serial numbers in a single request. It returns a list of trademarks that match the specified serial numbers.

22. What is the difference between the initial and pagination modes of the /v1/batchTrademarkSearch, /v1/batchTrademarkFullTextSearch, /v1/batchSerialSearch, and /v1/batchOwnerSearch endpoints?

• In initial mode, the initial request returns a scroll_id that can be used to retrieve the results of the search in multiple pages. This allows you to process a large number of results without having to load all of them at once.

• In pagination mode, you can specify the starting index and number of results to retrieve in each request. This allows you to iterate through the results of the search one page at a time.

  

Search Trademarks by keyword

  

23. What is the API endpoint to do a keyword search?

/v1/trademarkSearch

24. What is the purpose of the /v1/trademarkSearch endpoint?

The /v1/trademarkSearch endpoint allows you to search for trademarks based on specified keywords. It returns a list of trademarks that match the search criteria.

25. What information does the keyword search return?

• Trademark name, keyword
• Serial number
• Status
• Owner(s)
• Address
• Filing date
• Registration date
• Expiring date

26. What is the API endpoint to do a batch trademark search?

/v1/batchTrademarkSearch

27. How many credits does /v1/batchTrademarkSearch consume?

/v1/batchTrademarkSearch consumes as many credits as the number of keywords in your search array.

28. What is the API endpoint to do a batch trademark full text search?

/v1/batchTrademarkFullTextSearch

29. ** What is the difference between /v1/batchTrademarkFullTextSearch and /v1/trademarkFullTextSearch?**

/v1/batchTrademarkFullTextSearch allows you to perform a full-text keyword search on an array of keywords, while /v1/trademarkFullTextSearch only accepts a single keyword.

30. ** How many credits does /v1/batchTrademarkFullTextSearch consume?**

/v1/batchTrademarkFullTextSearch consumes 5 credits for the initial request and 0 credits for each subsequent pagination request.

  

Availability and expiration of trademarks

  

31. What is the API endpoint to check if a trademark is available?

/v1/trademarkAvailable

32. What information does the trademark availability check return?

The endpoint returns a simple “yes” or “no” response indicating whether the given keyword is available for use as a trademark.

33. What is the API endpoint to retrieve information about expiring trademarks?

/v1/trademarkExpiring

34. What is the purpose of the /v1/trademarkExpiring endpoint?

The endpoint retrieves a list of trademarks that are projected to expire within a specified date range. This can be useful for identifying trademarks that need to be renewed or abandoned.

35. What information does the expiring trademarks endpoint return?

• Trademark name, keyword
• Serial number
• Status
• Filing date
• Registration date
• Expiring date

36. How can I use /v1/trademarkExpiring to find trademarks that are expiring within a certain timeframe?

To use the endpoint, you need to specify a start_dateand end_date in your request. These days must be within 7 days of each other. You can use another call for next 7 days, The API will then return a list of trademarks whose projected renewal/expiration dates fall between those two dates.

  

Trademark Owner

  

37. What is the API endpoint to do an owner search?

/v1/ownerSearch

38. What information does the owner search return?

• Owner name
• Address
• E-mail if they have shared
• Trademarks owned

39. What is the API endpoint to do a batch owner search?

/v1/batchOwnerSearch

40. What information does the batch owner search return?

• Owner name
• Address
• E-mail if they have shared
• Trademarks owned

41. What is the purpose of the /v1/ownerSearch and /v1/batchOwnerSearch endpoints?

• /v1/ownerSearch performs a search based on an owner’s name or postcode and returns a list of trademarks that are owned by that person or organization.

• /v1/batchOwnerSearch allows you to search for multiple owner names or postcodes in a single request. It returns a list of trademarks that are owned by the specified people or organizations.

  

Batching + optimizing calls

  

42. How can I paginate through the results of a batch call?

You can use the scroll_id and start_index parameters to paginate through the results of a search. The scroll_id is obtained from the initial search request, and the start_index specifies the index of the first result to be returned in the next page of results.

43. How long does a scroll_id remain valid?

A scroll_id remains valid for approximately 24 hours. There is an expiration date field returned that you can use to your business case.

44. How do I handle pagination when retrieving large result sets?

The batch endpoints support pagination, allowing you to retrieve results in smaller batches. The initial call returns a scroll_id and the next_index to be used in the pagination call. Subsequent calls can then be made to retrieve additional results using the scroll ID and the next index.

45. Batch call doesn’t return any results? Why?

Batch calls are made of two steps.

1. The first step is init and doesn’t return results, but it returns the scroll_id context, that you use to pull results. In a nutshell 1st step, obtain scroll_id.
2. After init step, you just reuse scroll_id to fetch de results. This step doesn’t consume credits, and also it’s valid for 24 hours.

46. How does init batch call results look like?

Here is an example output:

{
 "requests": 1,
 "start_index": 0,
 "next_index": 0,
 "scroll_id": "L2I1QjQ1aHpKMXpIWXI4eG5UbUpwdnJmUFVvWStJNlBYenZFZ1NYUUlFdFZ6S241U29HbmNOaWFMVjhPU3BnM==",
 "scroll_expiration": 1706133388,
 "count": 297,
 "keywords": [
  "RCa"
 ]
}

This is a full output, and you see the following:

• The keywords used in search
• requests are credits consumed, this is equal to the number of keywords used.
• start_index, next_index drives pagination
• scroll_id is the context hash that you will need to use on the next call to fetch results.
• count is the number of results found
• scroll_expiration is the unix timestamp until when the results can be fetched. Usually 24 hours.

47. How does a batch pagination call results look like?

Below you will see result of a batch pagination call, input in this request was:

next_index 250
scroll_id = <token>

Output is below, and you can see.

• The request param being 0 means that no request credits were consumed. Pagination is free call.
• The start_index param being 250 means, that we want to retrieve 2nd page of results eg 250-297th results
• next_index signals the next call should start with this index, if this is equal to the count pagination reached the last page.
• scroll_id is the input context, you need to send this on every request.
• scroll_expiration is a unix timestamp signaling when the context will be lost. If case the results need to be rebuild again, just issue another search with no scroll_id.
• count indicates the total number of results available. Good to calculate the end of the pagination.

Raw output:

{
 "requests": 0,
 "start_index": 250,
 "next_index": 297,
 "scroll_id": "L2I1QjQ1aHpKMXpIWXI4eG5UbUpwdnJmUFVvWStJNlBYenZFZ1NYUUlFdFZ6S241U29HbmNOaWFMVjhPU3BnM==",
 "scroll_expiration": 1706133388,
 "count": 297,
 "keywords": [
  "RCa"
 ],
 "results": [
  {
"keyword": "RCAP RURAL COMMUNITY ASSISTANCE PARTNERSHIP",
"registration_number": "0000000",
"serial_number": "88976181",

48. How can I optimize my API calls to avoid excessive usage charges?

When using batch endpoints, consider the number of keywords or serial numbers you are searching for in each request to minimize the total number of requests made. Additionally, pay attention to the below headers to understand the actual RapidAPI request credits consumed by your calls.

• X-RapidAPI-Billing
• X-RapidAPI-Requests-limit
• X-RapidAPI-Requests-remaining