Converting an Existing Script

If you have a script that worked with the original R package and original version of the API, chances are it will need some possibly substantial changes before it will work with the new version of the R package and API.

Required API Key

First off you’ll need to request an API key and then set the environmental variable PATENTSVIEW_API_KEY to the value of your API key. Ex. set PATENTSVIEW_API_KEY=My_api_key Without a valid API key, all your calls will be rejected by the API.

The New Throttling Limit

Another new thing is a throttling limit. The new version of the API only allows an individual API key to make 45 calls per minute. The call that exceeds that limit is rejected but does return the number of seconds to wait before calls would be allowed again. Fortunately, the R package handles this for you! Your script will be chugging along and if the API should return a throttling response, the R package will sleep for the required number of seconds before automatically resending your query! The only thing you may notice, besides a warning message, it that the script will pause when throttled before it picks right back up again.

Philosophical Change

The new version of the API’s endpoints are less Swiss Army Knife-like than before, where you could get nearly any data field from any endpoint. Now they have substantially lighter responses and they generally focus on data pertinent to that endpoint. In other words, you can only get USPC fields from the USPC endpoints or from the patent endpoint. This may mean you’ll have to make multiple calls to different endpoints to get the same data the old version of API used to return in a single call.

Take a look at the top assignees application. It has to blend together information from separate calls that used to be returned by a single call. This may push your dplyr skills to the limit.

Changed Field Names and Types

The fields requested by the original script or used in its query may not be available from the new version’s endpoints. The nber attributes are no longer available as the nber_subcategories endpoint was removed. Also, some attributes have new names, like name_last in the nested inventor object returned by the patent endpoint. Now in the fields parameter it would be specified as “inventor.name_last” where formerly it was “inventor_last_name” when using the patent endpoint. This also demonstrates how nested fields need to be fully qualified in the query parameter.

Also note that some field’s types have changed, meaning you’ll need to use different operators within your query. Ex. assignee.organization is now a full text field, formerly it was a string.

library(patentsview)

# Before you could do a 
qry_funs$contains(assignee_organization="Rice University")
#> {"_contains":{"assignee_organization":"Rice University"}}

# now you would have to do 
qry_funs$text_phrase(assignees.assignee_organization="Rice University")
#> {"_text_phrase":{"assignees.assignee_organization":"Rice University"}}

Checkout the API documentation and the Swagger UI page to see the returned fields and their types. The same information is available in the fieldsdf data frame but it is harder to read.

Singular Endpoints

The endpoints are now singular, ex: “patent” where previously it was “patents”.

get_endpoints()
#>  [1] "assignee"                       "cpc_class"                     
#>  [3] "cpc_group"                      "cpc_subclass"                  
#>  [5] "g_brf_sum_text"                 "g_claim"                       
#>  [7] "g_detail_desc_text"             "g_draw_desc_text"              
#>  [9] "inventor"                       "ipc"                           
#> [11] "location"                       "patent"                        
#> [13] "patent/attorney"                "patent/foreign_citation"       
#> [15] "patent/other_reference"         "patent/rel_app_text"           
#> [17] "patent/us_application_citation" "patent/us_patent_citation"     
#> [19] "pg_brf_sum_text"                "pg_claim"                      
#> [21] "pg_detail_desc_text"            "pg_draw_desc_text"             
#> [23] "publication"                    "publication/rel_app_text"      
#> [25] "uspc_mainclass"                 "uspc_subclass"                 
#> [27] "wipo"

Additions to the R Package

Some of the endpoints now return HATEOAS links, where you make a call back to the API to retrieve additional data. The new method retrieve_linked_data() does just that.
There is a lot more about this here.

Conclusion

So there you have it, our attempt at listing what’s changed and what to do about it. Request an API key and get going with the new version of the R package! The two API versions will coexist for a while but the API team plans to shutdown the original version of the API in February 2025.