Skip to contents

Search PatentsView

Source: R/search-pv.R
search_pv.Rd

This function makes an HTTP request to the PatentsView API for data matching the user's query.

Usage

search_pv(
  query,
  fields = NULL,
  endpoint = "patents",
  subent_cnts = FALSE,
  mtchd_subent_only = lifecycle::deprecated(),
  page = 1,
  per_page = 1000,
  all_pages = FALSE,
  sort = NULL,
  method = "GET",
  error_browser = NULL,
  api_key = Sys.getenv("PATENTSVIEW_API_KEY"),
  ...
)

Arguments

query

The query that the API will use to filter records. query can come in any one of the following forms:

  • A character string with valid JSON.
    E.g., '{"_gte":{"patent_date":"2007-01-04"}}'

  • A list which will be converted to JSON by search_pv.
    E.g., list("_gte" = list("patent_date" = "2007-01-04"))

  • An object of class pv_query, which you create by calling one of the functions found in the qry_funs list...See the writing queries vignette for details.
    E.g., qry_funs$gte(patent_date = "2007-01-04")

fields

A character vector of the fields that you want returned to you. A value of NULL indicates that the default fields should be returned. Acceptable fields for a given endpoint can be found at the API's online documentation (e.g., check out the field list for the patents endpoint) or by viewing the fieldsdf data frame (View(fieldsdf)). You can also use get_fields to list out the fields available for a given endpoint.

endpoint

The web service resource you wish to search. Use get_endpoints() to list the available endpoints.

subent_cnts

[Deprecated] Non-matched subentities will always be returned under the new version of the API

mtchd_subent_only

[Deprecated] This is always FALSE in the new version of the API.

page

The page number of the results that should be returned.

per_page

The number of records that should be returned per page. This value can be as high as 1,000 (e.g., per_page = 1000).

all_pages

Do you want to download all possible pages of output? If all_pages = TRUE, the values of page and per_page are ignored.

sort

A named character vector where the name indicates the field to sort by and the value indicates the direction of sorting (direction should be either "asc" or "desc"). For example, sort = c("patent_number" = "asc") or
sort = c("patent_number" = "asc", "patent_date" = "desc"). sort = NULL (the default) means do not sort the results. You must include any fields that you wish to sort by in fields.

method

The HTTP method that you want to use to send the request. Possible values include "GET" or "POST". Use the POST method when your query is very long (say, over 2,000 characters in length).

error_browser

[Deprecated]

api_key

API key. See Here for info on creating a key.

...

Arguments passed along to httr's GET or POST function.

Value

A list with the following three elements:

data

A list with one element - a named data frame containing the data returned by the server. Each row in the data frame corresponds to a single value for the primary entity. For example, if you search the assignees endpoint, then the data frame will be on the assignee-level, where each row corresponds to a single assignee. Fields that are not on the assignee-level would be returned in list columns.

query_results

Entity counts across all pages of output (not just the page returned to you).

request

Details of the HTTP request that was sent to the server. When you set all_pages = TRUE, you will only get a sample request. In other words, you will not be given multiple requests for the multiple calls that were made to the server (one for each page of results).

Examples

if (FALSE) { # \dontrun{

search_pv(query = '{"_gt":{"patent_year":2010}}')

search_pv(
  query = qry_funs$gt(patent_year = 2010),
  fields = get_fields("patents", c("patents", "assignees_at_grant"))
)

search_pv(
  query = qry_funs$gt(patent_year = 2010),
  method = "POST",
  fields = "patent_number",
  sort = c("patent_number" = "asc")
)

search_pv(
  query = qry_funs$eq(name_last = "crew"),
  endpoint = "inventors",
  all_pages = TRUE
)

search_pv(
  query = qry_funs$contains(name_last = "smith"),
  endpoint = "assignees"
)

search_pv(
  query = qry_funs$contains(inventors_at_grant.name_last = "smith"),
  endpoint = "patents",
  config = httr::timeout(40)
)
} # }