You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.Rmd
+2-2
Original file line number
Diff line number
Diff line change
@@ -54,7 +54,7 @@ install.packages("patentsview")
54
54
```
55
55
## Important API Change
56
56
57
-
The new version of the API requires an api key, or all of your requests will be blocked. An API key can be optained[here](https://patentsview.org/apis/keyrequest). The updated R package will look for an environmental variable PATENTSVIEW_API_KEY set to the value of your key. For windows it would be
57
+
The new version of the API requires an API key, or all of your requests will be blocked. An API key can be obtained[here](https://patentsview.org/apis/keyrequest). The updated R package will look for an environmental variable PATENTSVIEW_API_KEY set to the value of your key. For windows it would be
58
58
```
59
59
set PATENTSVIEW_API_KEY=my_keys_value_without quotes
60
60
```
@@ -83,4 +83,4 @@ Head over to the package's [webpage](https://docs.ropensci.org/patentsview/index
83
83
This package was first introduced in 2017 in an [rOpenSci blog post](https://ropensci.org/blog/2017/09/19/patentsview/) which
84
84
used the original version of the API. The same content, reworked to use the new version
85
85
of the API, is available [here](articles/ropensci_blog_post.html). A draft of a possible Tech Note
86
-
about the new version of the API and R package is [here]().
86
+
about the new version of the API and R package is [here]().
Copy file name to clipboardexpand all lines: vignettes/api-changes.Rmd
+21-21
Original file line number
Diff line number
Diff line change
@@ -9,21 +9,21 @@ vignette: >
9
9
10
10
11
11
12
-
In July of 2021 the Patentview API team announced [upcoming API changes](https://patentsview.org/data-in-action/whats-new-patentsview-july-2021). This page will explain the changes and impact to the
13
-
[R package](#r-package-changes). Note that these are **breaking changes**, existing scripts will no longer run as-is using the new version of the API and the new version of the R package.
12
+
In July of 2021 the Patentsview API team announced [upcoming API changes](https://patentsview.org/data-in-action/whats-new-patentsview-july-2021). This page will explain the changes and impact to the
13
+
[R package](#r-package-changes). Note that these are **breaking changes**, existing scripts will no longer run as-is using the the new version of the R package which uses the new version of the API.
14
14
15
15
## Summary of the API changes
16
-
* Probably most importanly, the current shutdown date for the original version of the API
16
+
* Probably most importantly, the current shutdown date for the original version of the API
17
17
is February 12, 2025, as communicated in the August 2024 newsletter.
18
18
* An [API key](#api-key-required) is now required.
19
19
* All fields can be queried now and there is seemingly [no distinction](#operators) between using string and full text operators now, with a new [case sensitivity caveat](#case-sensitivity-caveat) though. Note that now some
20
20
fields are returned in nested objects and would need to be fully qualified in the query/q: and
21
-
fields/f: paramters. Ex. fields=c( "cpc_current.cpc_group_id") is used below.
21
+
fields/f: parameters. Ex. fields=c( "cpc_current.cpc_group_id") is used below.
22
22
* A result set's size seems unbounded now, you can now retrieve more than 100,000 rows. You'd need to be careful when setting all_pages = TRUE
23
23
as the R package will page until the entire result set is retrieved which could be a million or more rows. Ex. search_pv('{"patent_type":"utility"}', all_pages=TRUE)
24
24
25
25
* Endpoint Changes
26
-
- nber_subcategories went away- it was an endpoint in the original verson of the API
26
+
- nber_subcategories went away- it was an endpoint in the original version of the API
27
27
- Endpoints are now singular, ex. patent not patents. The returned entities are still plural for the most part.
28
28
- Now there are [23 endpoints](#endpoints), up from the original 7
29
29
@@ -63,7 +63,7 @@ The Patentsview API team has provided a Swagger UI page for the new version of t
63
63
- /api/v1/publication/rel_app_text/
64
64
- /api/v1/publications/
65
65
- /api/v1/wipo/
66
-
2. Five of the original api's endpoints have singular names but lighter responses and fewer queryable fields as mentioned above.
66
+
2. Five of the original API's endpoints have singular names but lighter responses and fewer queryable fields as mentioned above.
67
67
- /api/v1/assignee/
68
68
- /api/v1/inventor/
69
69
- /api/v1/location/
@@ -85,10 +85,10 @@ Things to note
85
85
86
86
87
87
### HATEOAS Links <aname="HATEOAS">
88
-
Some of the returned fields are HATEOAS (Hypermedia as the Engine of Application State) links to retrieve more information about that field. Slightly funky is the cpc_current's cpc_group, returned by the patents endpoint. Here the slash in the CPC is turned into a colon. This is a peculiarity of two of the new convience urls that shouldn't be noticable in the r package, unless you are trying to infer the USPC and CPC values from the returned urls, without actually calling back for this data.
88
+
Some of the returned fields are HATEOAS (Hypermedia as the Engine of Application State) links to retrieve more information about that field. Slightly funky is the cpc_current's cpc_group, returned by the patents endpoint. Here the slash in the CPC is turned into a colon. This is a peculiarity of two of the new convenience urls that shouldn't be noticeable in the r package, unless you are trying to infer the USPC and CPC values from the returned urls, without actually calling back for this data.
89
89
90
-
Here we'll call the patent endpoint to get CPC fields for a particular patend, some of
91
-
the fields, like the cpc_group, are HATEOAS links:
90
+
Here we'll call the patent endpoint to get CPC fields for a particular patent, some of
91
+
the returned fields, like the cpc_group, are HATEOAS links:
92
92
93
93
94
94
```r
@@ -105,11 +105,11 @@ library(patentsview)
105
105
106
106
result<- search_pv(query, fields=fields)
107
107
108
-
#as noted above, the CPC related fields aren't the same as they were in the
108
+
#As noted above, the CPC related fields aren't the same as they were in the
109
109
# original version of the API. Also note that not all requested fields were
110
110
# returned and that _id-less, HATEOAS fields were returned.
Note that going to these links in a browser will result in a 403 Unauthorized, as no API key is sent.
125
125
126
-
There is a new method in the R package to retrive data from the HATEOAS links, just pass the returned
126
+
There is a new method in the R package to retrieve data from the HATEOAS links, just pass the returned
127
127
link and the R package will retrieve the data for you. You can also pass an arbitrary link that hits
128
-
the API. This can be particualarly useful if you want to see what the response would be from a link
128
+
the API. This can be particularly useful if you want to see what the response would be from a link
129
129
found in the [API's documentation](https://search.patentsview.org/docs/docs/Search%20API/SearchAPIReference/).
130
130
131
131
@@ -209,7 +209,7 @@ Slight weirdness/sleight of hand where the returned field name looses the _id of
209
209
```
210
210
211
211
### Throttling <aname="throttling"></a>
212
-
The API will now allow 45 requests per minute, making more requests will anger the API. It will send back an error code with a header indicating how many seconds to wait before sending more queries. The R package will take care of this for you. It will sleep for the required number of seconds before resubmitting your query, seemlessly to your script.
212
+
The API will now allow 45 requests per minute, making more requests will anger the API. It will send back an error code with a header indicating how many seconds to wait before sending more queries. The R package will take care of this for you. It will sleep for the required number of seconds before resubmitting your query, seamlessly to your script.
213
213
214
214
This means that queries could take a lot longer to run now. Ex. a query that would
215
215
return 100,000 rows would now take 3.7 hours to run as each request can return at most 1,000 rows.
@@ -218,7 +218,7 @@ return 100,000 rows would now take 3.7 hours to run as each request can return a
218
218
219
219
220
220
### A Note on Paging <aname="a-note-on-paging">
221
-
The API team changed how paging works and there is an important subtility that the R package
221
+
The API team changed how paging works and there is an important subtlety that the R package
222
222
handles for you. This screams for a python library so python users don't need to worry about this and
223
223
throttling! Here's a comment in search-pv.R that tries to explain the danger.
224
224
```
@@ -230,7 +230,7 @@ throttling! Here's a comment in search-pv.R that tries to explain the danger.
230
230
231
231
# Doing this also protects users from needing to know the peculiarities
232
232
# of the API's paging. Example: if a user requests a sort of
233
-
# {"patent_date":"asc"}, on paging the after parameter may skip
233
+
# [{"patent_date":"asc"}], on paging the after parameter may skip
234
234
# to the next issue date before having retured all the data for the last
235
235
# patent_date in the previous request - depending on where the
236
236
# patent_dates change relative to the API's page breaks.
@@ -243,7 +243,7 @@ throttling! Here's a comment in search-pv.R that tries to explain the danger.
243
243
See the paging discussion in this [PR](https://github.com/ropensci/patentsview/pull/29#discussion_r1059137212)
244
244
245
245
### String and Full Text Operators <aname="operators">
246
-
The Tip below "Syntax" in the API's [documentation](https://search.patentsview.org/docs/docs/Search%20API/SearchAPIReference/#syntax) says
246
+
The Tip below "Syntax" in the API's [documentation](https://search.patentsview.org/docs/docs/Search%20API/SearchAPIReference/#syntax) says:
247
247
248
248
When working with text data fields, wherever possible, we recommend using _text* operators over the
249
249
_contains and _begins operator. The text operators treat these fields as full text data and hence
0 commit comments