RSC Filter API
Search and filter chemical compounds by various properties.
OpenAPI Specification
openapi: 3.1.0
info:
title: RSC ChemSpider Compounds Filter API
description: The RSC ChemSpider Compounds API provides programmatic access to the ChemSpider chemical database, which contains over 88 million unique chemical compounds. The API supports compound searching by name, SMILES, InChI, InChIKey, molecular formula, mass, and elemental composition. Authenticated users can retrieve compound records with detailed properties, fetch external references, images, and MOL files, and perform batch operations. A tools endpoint supports chemical format conversions and InChIKey validation. All requests require an API key obtained from the RSC Developer Portal.
version: '1'
contact:
name: RSC Developer Support
url: https://developer.rsc.org/
termsOfService: https://www.rsc.org/legal/
servers:
- url: https://api.rsc.org/compounds/v1
description: ChemSpider Production API
tags:
- name: Filter
description: Search and filter chemical compounds by various properties.
paths:
/filter/name:
post:
operationId: filterByName
summary: Filter Compounds By Name
description: Submit a name query to search for chemical compounds matching the specified name. Returns a query ID that can be used to poll for results using the filter status and results endpoints.
tags:
- Filter
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: The compound name to search for
orderBy:
type: string
description: Sort field for results
enum:
- recordId
- massDefect
- molecularWeight
- referenceCount
- dataSourceCount
- pubmedCount
- rscCount
orderDirection:
type: string
description: Sort direction
enum:
- ascending
- descending
responses:
'200':
description: Query accepted; returns query ID
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
'400':
description: Invalid request
'401':
description: Unauthorized - API key missing or invalid
security:
- apiKeyAuth: []
/filter/smiles:
post:
operationId: filterBySmiles
summary: Filter Compounds By SMILES
description: Submit a SMILES string to find matching chemical compounds. Returns a query ID for polling results.
tags:
- Filter
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- smiles
properties:
smiles:
type: string
description: The SMILES string for the compound
orderBy:
type: string
description: Sort field for results
orderDirection:
type: string
description: Sort direction
responses:
'200':
description: Query accepted; returns query ID
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
'401':
description: Unauthorized
security:
- apiKeyAuth: []
/filter/inchi:
post:
operationId: filterByInchi
summary: Filter Compounds By InChI
description: Submit an InChI string to find matching chemical compounds. Returns a query ID for polling results.
tags:
- Filter
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- inchi
properties:
inchi:
type: string
description: The InChI string for the compound
responses:
'200':
description: Query accepted; returns query ID
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
'401':
description: Unauthorized
security:
- apiKeyAuth: []
/filter/inchikey:
post:
operationId: filterByInchikey
summary: Filter Compounds By InChIKey
description: Submit an InChIKey to find the matching chemical compound. Returns a query ID for polling results.
tags:
- Filter
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- inchikey
properties:
inchikey:
type: string
description: The InChIKey for the compound
responses:
'200':
description: Query accepted; returns query ID
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
'401':
description: Unauthorized
security:
- apiKeyAuth: []
/filter/formula:
post:
operationId: filterByFormula
summary: Filter Compounds By Formula
description: Search for compounds matching a given molecular formula. Optionally restrict to specific data sources.
tags:
- Filter
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- formula
properties:
formula:
type: string
description: Molecular formula (e.g., C6H12O6)
dataSources:
type: array
items:
type: string
description: List of data sources to restrict search
orderBy:
type: string
description: Sort field
orderDirection:
type: string
description: Sort direction
responses:
'200':
description: Query accepted; returns query ID
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
'401':
description: Unauthorized
security:
- apiKeyAuth: []
/filter/mass:
post:
operationId: filterByMass
summary: Filter Compounds By Mass
description: Search for compounds within a mass range. The mass and mass_range parameters define the target mass and acceptable deviation.
tags:
- Filter
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- mass
- massRange
properties:
mass:
type: number
description: Target molecular mass
massRange:
type: number
description: Acceptable mass deviation (+/-)
dataSources:
type: array
items:
type: string
description: Data sources to restrict search
orderBy:
type: string
description: Sort field
orderDirection:
type: string
description: Sort direction
responses:
'200':
description: Query accepted; returns query ID
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
'401':
description: Unauthorized
security:
- apiKeyAuth: []
/filter/{queryId}/status:
get:
operationId: getFilterStatus
summary: Get Filter Query Status
description: Poll the status of a previously submitted filter query using its query ID. Returns the current status, result count, and any message.
tags:
- Filter
parameters:
- name: queryId
in: path
required: true
schema:
type: string
description: The query ID returned by a filter endpoint
responses:
'200':
description: Query status
content:
application/json:
schema:
$ref: '#/components/schemas/FilterStatus'
'401':
description: Unauthorized
'404':
description: Query not found
security:
- apiKeyAuth: []
/filter/{queryId}/results:
get:
operationId: getFilterResults
summary: Get Filter Query Results
description: Retrieve the record IDs for a completed filter query. Supports pagination via start and count parameters.
tags:
- Filter
parameters:
- name: queryId
in: path
required: true
schema:
type: string
description: The query ID returned by a filter endpoint
- name: start
in: query
required: false
schema:
type: integer
minimum: 0
description: Zero-based index of first result to return
- name: count
in: query
required: false
schema:
type: integer
minimum: 1
description: Number of results to return
responses:
'200':
description: Array of record IDs
content:
application/json:
schema:
$ref: '#/components/schemas/FilterResults'
'401':
description: Unauthorized
'404':
description: Query not found
security:
- apiKeyAuth: []
components:
schemas:
FilterResults:
type: object
description: Results from a completed filter query
properties:
queryId:
type: string
description: The query ID
results:
type: array
items:
type: integer
description: Array of ChemSpider record IDs matching the query
FilterStatus:
type: object
description: Status of a filter query
properties:
status:
type: string
description: Current query status (Processing, Complete, Failed)
enum:
- Processing
- Complete
- Failed
count:
type: integer
description: Number of results found so far
message:
type: string
description: Status message or error description
QueryResponse:
type: object
description: Response from a filter query submission
properties:
queryId:
type: string
description: Unique identifier for the submitted query
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: apikey
description: API key obtained from the RSC Developer Portal at developer.rsc.org. Register and create an application to receive an API key.