0047ce96a8
* fix: don't trigger `url` remote document load if `urls` is provided * better test block title
211 lines
7.6 KiB
YAML
211 lines
7.6 KiB
YAML
openapi: 3.0.1
|
|
servers:
|
|
- url: '{scheme}://developer.uspto.gov/ds-api'
|
|
variables:
|
|
scheme:
|
|
description: 'The Data Set API is accessible via https and http'
|
|
enum:
|
|
- 'https'
|
|
- 'http'
|
|
default: 'https'
|
|
info:
|
|
description: >-
|
|
The Data Set API (DSAPI) allows the public users to discover and search
|
|
USPTO exported data sets. This is a generic API that allows USPTO users to
|
|
make any CSV based data files searchable through API. With the help of GET
|
|
call, it returns the list of data fields that are searchable. With the help
|
|
of POST call, data can be fetched based on the filters on the field names.
|
|
Please note that POST call is used to search the actual data. The reason for
|
|
the POST call is that it allows users to specify any complex search criteria
|
|
without worry about the GET size limitations as well as encoding of the
|
|
input parameters.
|
|
version: 1.0.0
|
|
title: USPTO Data Set API
|
|
contact:
|
|
name: Open Data Portal
|
|
url: 'https://developer.uspto.gov'
|
|
email: developer@uspto.gov
|
|
tags:
|
|
- name: metadata
|
|
description: Find out about the data sets
|
|
- name: search
|
|
description: Search a data set
|
|
paths:
|
|
/:
|
|
get:
|
|
tags:
|
|
- metadata
|
|
operationId: list-data-sets
|
|
summary: List available data sets
|
|
responses:
|
|
'200':
|
|
description: Returns a list of data sets
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/dataSetList'
|
|
example:
|
|
{
|
|
"total": 2,
|
|
"apis": [
|
|
{
|
|
"apiKey": "oa_citations",
|
|
"apiVersionNumber": "v1",
|
|
"apiUrl": "https://developer.uspto.gov/ds-api/oa_citations/v1/fields",
|
|
"apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/oa_citations.json"
|
|
},
|
|
{
|
|
"apiKey": "cancer_moonshot",
|
|
"apiVersionNumber": "v1",
|
|
"apiUrl": "https://developer.uspto.gov/ds-api/cancer_moonshot/v1/fields",
|
|
"apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/cancer_moonshot.json"
|
|
}
|
|
]
|
|
}
|
|
/{dataset}/{version}/fields:
|
|
get:
|
|
tags:
|
|
- metadata
|
|
summary: >-
|
|
Provides the general information about the API and the list of fields
|
|
that can be used to query the dataset.
|
|
description: >-
|
|
This GET API returns the list of all the searchable field names that are
|
|
in the oa_citations. Please see the 'fields' attribute which returns an
|
|
array of field names. Each field or a combination of fields can be
|
|
searched using the syntax options shown below.
|
|
operationId: list-searchable-fields
|
|
parameters:
|
|
- name: dataset
|
|
in: path
|
|
description: 'Name of the dataset.'
|
|
required: true
|
|
example: "oa_citations"
|
|
schema:
|
|
type: string
|
|
- name: version
|
|
in: path
|
|
description: Version of the dataset.
|
|
required: true
|
|
example: "v1"
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: >-
|
|
The dataset API for the given version is found and it is accessible
|
|
to consume.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: string
|
|
'404':
|
|
description: >-
|
|
The combination of dataset name and version is not found in the
|
|
system or it is not published yet to be consumed by public.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: string
|
|
/{dataset}/{version}/records:
|
|
post:
|
|
tags:
|
|
- search
|
|
summary: >-
|
|
Provides search capability for the data set with the given search
|
|
criteria.
|
|
description: >-
|
|
This API is based on Solr/Lucense Search. The data is indexed using
|
|
SOLR. This GET API returns the list of all the searchable field names
|
|
that are in the Solr Index. Please see the 'fields' attribute which
|
|
returns an array of field names. Each field or a combination of fields
|
|
can be searched using the Solr/Lucene Syntax. Please refer
|
|
https://lucene.apache.org/core/3_6_2/queryparsersyntax.html#Overview for
|
|
the query syntax. List of field names that are searchable can be
|
|
determined using above GET api.
|
|
operationId: perform-search
|
|
parameters:
|
|
- name: version
|
|
in: path
|
|
description: Version of the dataset.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: v1
|
|
- name: dataset
|
|
in: path
|
|
description: 'Name of the dataset. In this case, the default value is oa_citations'
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: oa_citations
|
|
responses:
|
|
'200':
|
|
description: successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
'404':
|
|
description: No matching record found for the given criteria.
|
|
requestBody:
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
criteria:
|
|
description: >-
|
|
Uses Lucene Query Syntax in the format of
|
|
propertyName:value, propertyName:[num1 TO num2] and date
|
|
range format: propertyName:[yyyyMMdd TO yyyyMMdd]. In the
|
|
response please see the 'docs' element which has the list of
|
|
record objects. Each record structure would consist of all
|
|
the fields and their corresponding values.
|
|
type: string
|
|
default: '*:*'
|
|
start:
|
|
description: Starting record number. Default value is 0.
|
|
type: integer
|
|
default: 0
|
|
rows:
|
|
description: >-
|
|
Specify number of rows to be returned. If you run the search
|
|
with default values, in the response you will see 'numFound'
|
|
attribute which will tell the number of records available in
|
|
the dataset.
|
|
type: integer
|
|
default: 100
|
|
required:
|
|
- criteria
|
|
components:
|
|
schemas:
|
|
dataSetList:
|
|
type: object
|
|
properties:
|
|
total:
|
|
type: integer
|
|
apis:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
apiKey:
|
|
type: string
|
|
description: To be used as a dataset parameter value
|
|
apiVersionNumber:
|
|
type: string
|
|
description: To be used as a version parameter value
|
|
apiUrl:
|
|
type: string
|
|
format: uriref
|
|
description: "The URL describing the dataset's fields"
|
|
apiDocumentationUrl:
|
|
type: string
|
|
format: uriref
|
|
description: A URL to the API console for each API
|