Interrogate and access chemical data, powered by the Royal Society of Chemistry's ChemSpider database.

filtering

Method
Description

POST

filter-element-post

https://api.rsc.org/compounds/v1/filter/element

Submit an array called 'includeElements' of up to 15 elements and an array called 'excludeElements' of up to 100 elements via POST. This endpoint will then return compounds that both include the elements in the includeElements array and exclude elements in the excludeElements array. Optionally, you can also submit orderBy and orderDirection to specify the sort order for the results. Valid values for orderBy are recordId, massDefect, molecularWeight, referenceCount, dataSourceCount, pubMedCount, rscCount. Valid values for orderDirection are ascending, descending. You can also supply an object called 'options', which takes three key-value pairs, called 'includeAll', 'complexity' and 'isotopic'. The default behavior is to consider records which contain any of the elements listed in the includeElements array. Setting includeAll to true will only consider records which contain all the elements listed in the includeElements array. Valid values for complexity are 'any', 'single', or 'multiple' whereby a compound with a complexity of multiple has more than one disconnected system in it or a metal atom or ion. Valid values for isotopic are 'any', 'labeled', or 'unlabeled'. If successful, returns a Query ID representing the search. If not successful, returns an HTTP status other than 200. After running this search, iteratively send the returned Query ID to /filter/{queryId}/status to check the status of the asynchronous query. When the status is 'Complete', send the Query ID to /filter/{queryId}/results to obtain the result.

POST

filter-formula-batch-post

https://api.rsc.org/compounds/v1/filter/formula/batch

Submit an array of up to 100 formulas via POST. You can optionally supply dataSources as a JSON-formatted array of up to 20 strings, representing the data sources to query. You can obtain valid values from the /lookups/datasources endpoint. If dataSources is not specified, all known sources are searched. This will take longer. Optionally, you can also submit orderBy and orderDirection to specify the sort order for the results. Valid values for orderBy are recordId, massDefect, molecularWeight, referenceCount, dataSourceCount, pubMedCount, rscCount. Valid values for orderDirection are ascending, descending. If successful, returns a Query ID representing the search. If not successful, returns an HTTP status other than 200. After running this search, iteratively send the returned Query ID to /filter/formula/batch/{queryId}/status to check the status of the asynchronous query. When the status is 'Complete', send the Query ID to /filter/formula/batch/{queryId}/results to obtain the result.

GET

filter-formula-batch-queryId-results-get

https://api.rsc.org/compounds/v1/filter/formula/batch/{queryId}/results

Call this endpoint with a queryId returned from the /filter/formula/batch filter query. The queryId supplied must return 'Complete' when submitted to /filter/formula/batch/{queryId}/status If successful, returns a JSON array of results from the query. The results are represented as Record IDs. You can send the Record ID to any of the /record/ endpoints for more information on the compound. If not successful, returns an HTTP status other than 200.

GET

filter-formula-batch-queryId-status-get

https://api.rsc.org/compounds/v1/filter/formula/batch/{queryId}/status

Call this endpoint with a queryId returned from the /filter/formula/batch filter query. If successful, returns a JSON object. This object contains 'status', which is the status of the query represented by the queryId. When the status is 'Complete', the object also contains 'count', which is the number of results returned. If not successful, returns an HTTP status other than 200. After receiving a status of 'Complete' from this endpoint, send the Query ID to /filter/formula/batch/{queryId}/results to obtain the result. We recommend that you wait at least 10 seconds before calling this endpoint, and then call this endpoint every 5 seconds. You should stop calling this endpoint when the status changes to Suspended, Failed, Not Found or Complete. A status of Suspended can be caused if the results could not be compiled within a reasonable amount of time. Create a new filter request with more restrictive parameters. A status of Failed can be caused if the backend system could not compile the results. Create a new filter request and, if the same outcome occurs, apply more restrictive parameters. A status of Not Found can be caused if the Query ID has not been registered or has expired; create a new filter request.

POST

filter-formula-post

https://api.rsc.org/compounds/v1/filter/formula

Submit formula as a string via POST. You can optionally supply dataSources as a JSON-formatted array of up to 20 strings, representing the data sources to query. You can obtain valid values from the /lookups/datasources endpoint. If dataSources is not specified, all known sources are searched. This will take longer. Optionally, you can also submit orderBy and orderDirection to specify the sort order for the results. Valid values for orderBy are recordId, massDefect, molecularWeight, referenceCount, dataSourceCount, pubMedCount, rscCount. Valid values for orderDirection are ascending, descending. If successful, returns a Query ID representing the search. If not successful, returns an HTTP status other than 200. After running this search, iteratively send the returned Query ID to /filter/{queryId}/status to check the status of the asynchronous query. When the status is 'Complete', send the Query ID to /filter/{queryId}/results to obtain the result.

POST

filter-inchi-post

https://api.rsc.org/compounds/v1/filter/inchi

Submit an InChI as a string via POST. If successful, returns a Query ID representing the search. If not successful, returns an HTTP status other than 200. After running this search, iteratively send the returned Query ID to /filter/{queryId}/status to check the status of the asynchronous query. When the status is 'Complete', send the Query ID to /filter/{queryId}/results to obtain the result.

POST

filter-inchikey-post

https://api.rsc.org/compounds/v1/filter/inchikey

Submit an InChIKey as a string via POST. If successful, returns a Query ID representing the search. If not successful, returns an HTTP status other than 200. After running this search, iteratively send the returned Query ID to /filter/{queryId}/status to check the status of the asynchronous query. When the status is 'Complete', send the Query ID to /filter/{queryId}/results to obtain the result.

POST

filter-intrinsicproperty-post

https://api.rsc.org/compounds/v1/filter/intrinsicproperty

Submit a formula as a string or a weight via POST. At least one of formula, molecularWeight, nominalMass, averageMass, monoisotopicMass must be specified. Complexity and isotopic are optional. See the example for more information. Valid values for complexity are 'any', 'single', or 'multiple' whereby a compound with a complexity of multiple has more than one disconnected system in it or a metal atom or ion. Valid values for isotopic are 'any', 'labeled', or 'unlabeled'. You can use orderBy and orderDirection to specify the sort order for the results. Valid values for orderBy are recordId, massDefect, molecularWeight, referenceCount, dataSourceCount, pubMedCount, rscCount. Valid values for orderDirection are ascending, descending. If successful, returns a Query ID representing the search. If not successful, returns an HTTP status other than 200. After running this search, iteratively send the returned Query ID to /filter/{queryId}/status to check the status of the asynchronous query. When the status is 'Complete', send the Query ID to /filter/{queryId}/results to obtain the result.

POST

filter-mass-batch-post

https://api.rsc.org/compounds/v1/filter/mass/batch

You can use this endpoint when you have multiple masses to search as a batch. Submit an array of up to 20 monoisotopic masses via POST. Each item in the array is an object with properties 'mass' and 'range'. Submit mass as a double between 1 and 11000 Atomic Mass Units, and a range between 0.0001 and 0.02. For example, if you specify a monoisotopic mass of 40 and a range of 0.0005, all masses between 39.9995 and 40.0005 are searched. You can optionally supply dataSources as a JSON-formatted array of up to 20 strings, representing the data sources to query. You can obtain valid values from the /lookups/datasources endpoint. If dataSources is not specified, all known sources are searched. This will take longer. Optionally, you can also submit orderBy and orderDirection to specify the sort order for the results. If you do not specify a value for orderBy, results are sorted by Record ID by default. Valid values for orderBy are recordId, massDefect, molecularWeight, referenceCount, dataSourceCount, pubMedCount, rscCount. Valid values for orderDirection are ascending, descending. If successful, returns a Query ID representing the search. If not successful, returns an HTTP status other than 200. After running this search, iteratively send the returned Query ID to /filter/mass/batch/{queryId}/status to check the status of the asynchronous query. When the status is 'Complete', send the Query ID to /filter/mass/batch/{queryId}/results to obtain the result.

GET

filter-mass-batch-queryId-results-get

https://api.rsc.org/compounds/v1/filter/mass/batch/{queryId}/results

Call this endpoint with a queryId returned from the /filter/mass/batch filter query. The queryId supplied must return 'Complete' when submitted to /filter/mass/batch/{queryId}/status If successful, returns a JSON array of results from the query. The results are represented as Record IDs with their respective masses and the defect from the query mass to the record mass. You can send the Record ID to any of the /record/ endpoints for more information on the compound. If not successful, returns an HTTP status other than 200.

GET

filter-mass-batch-queryId-status-get

https://api.rsc.org/compounds/v1/filter/mass/batch/{queryId}/status

Call this endpoint with a queryId returned from the /filter/mass/batch filter query. If successful, returns a JSON object. This object contains 'status', which is the status of the query represented by the queryId. When the status is 'Complete', the object also contains 'count', which is the number of results returned. If not successful, returns an HTTP status other than 200. After receiving a status of 'Complete' from this endpoint, send the Query ID to /filter/mass/batch/{queryId}/results to obtain the result. We recommend that you wait at least 10 seconds before calling this endpoint, and then call this endpoint every 5 seconds. You should stop calling this endpoint when the status changes to Suspended, Failed, Not Found or Complete. A status of Suspended can be caused if the results could not be compiled within a reasonable amount of time. Create a new filter request with more restrictive parameters. A status of Failed can be caused if the backend system could not compile the results. Create a new filter request and, if the same outcome occurs, apply more restrictive parameters. A status of Not Found can be caused if the Query ID has not been registered or has expired. Create a new filter request.

POST

filter-mass-post

https://api.rsc.org/compounds/v1/filter/mass

Submit mass as a double between 1 and 11000 Atomic Mass Units, and a range between 0.0001 and 100 via POST. For example, if you specify a mass of 40 and a range of 5, all monoisotopic masses between 35 and 45 are searched. You can optionally supply dataSources as a JSON-formatted array of up to 20 strings, representing the data sources to query. You can obtain valid values from the /lookups/datasources endpoint. If dataSources is not specified, all known sources are searched. This will take longer. Optionally, you can also submit orderBy and orderDirection to specify the sort order for the results. If you do not specify a value for orderBy, results are sorted by Record ID by default. Valid values for orderBy are recordId, massDefect, molecularWeight, referenceCount, dataSourceCount, pubMedCount, rscCount. Valid values for orderDirection are ascending, descending. If successful, returns a Query ID representing the search. If not successful, returns an HTTP status other than 200. After running this search, iteratively send the returned Query ID to /filter/{queryId}/status to check the status of the asynchronous query. When the status is 'Complete', send the Query ID to /filter/{queryId}/results to obtain the result.

POST

filter-name-post

https://api.rsc.org/compounds/v1/filter/name

Submit a compound name as a string via POST. Optionally, you can also submit orderBy and orderDirection to specify the sort order for the results. If you do not specify a value for orderBy, results are sorted by Record ID by default. Valid values for orderBy are recordId, massDefect, molecularWeight, referenceCount, dataSourceCount, pubMedCount, rscCount. Valid values for orderDirection are ascending, descending. If successful, returns a Query ID representing the search. If not successful, returns an HTTP status other than 200. After running this search, iteratively send the returned Query ID to /filter/{queryId}/status to check the status of the asynchronous query. When the status is 'Complete', send the Query ID to /filter/{queryId}/results to obtain the result.

GET

filter-queryId-results-get

https://api.rsc.org/compounds/v1/filter/{queryId}/results

Call this endpoint with a queryId returned from another filter query. The queryId supplied must return 'Complete' when submitted to /filter/{queryId}/status If successful, returns a JSON array of results from the query. The results are represented as Record IDs. You can send the Record ID to any of the /record/ endpoints for more information on the compound. If not successful, returns an HTTP status other than 200. If the results have been truncated because there were more results than the maximum number of results permitted (by default, 10,000), limitedToMaxAllowed is set to True. If this happens, you can split your requests into smaller batches. To batch your requests, call this endpoint with two optional parameters, 'start' and 'count'. Both take integer values. 'start' is the number of the record to start with (zero-based), and 'count' is the number of records to return. For example, to request results 200-300, send '?start=200&count=100'.

GET

filter-queryId-results-sdf-get

https://api.rsc.org/compounds/v1/filter/{queryId}/results/sdf

Call this endpoint with a queryId returned from another filter query. The queryId supplied must return 'Complete' when submitted to /filter/{queryId}/status If successful, returns all of the results from the query as an SDF file. A maximum of 10,000 records are returned as a single base64-encoded gZipped SDF. If not successful, returns an HTTP status other than 200. (This is identical to calling /record/{recordId}/mol)

GET

filter-queryId-status-get

https://api.rsc.org/compounds/v1/filter/{queryId}/status

Call this endpoint with a queryId returned from another filter query. If successful, returns a JSON object. This object contains 'status', which is the status of the query represented by the queryId. When the status is 'Complete', the object also contains 'count', which is the number of results returned. If not successful, returns an HTTP status other than 200. After receiving a status of 'Complete' from this endpoint, send the Query ID to /filter/{queryId}/results to obtain the result. We recommend that you wait at least 10 seconds before calling this endpoint, and then call this endpoint every 5 seconds. You should stop calling this endpoint when the status changes to Suspended, Failed, Not Found or Complete. A status of Suspended can be caused if the results could not be compiled within a reasonable amount of time. Create a new filter request with more restrictive parameters. A status of Failed can be caused if the backend system could not compile the results. Create a new filter request and, if the same outcome occurs, apply more restrictive parameters. A status of Not Found can be caused if the Query ID has not been registered or has expired. Create a new filter request.

POST

filter-smiles-post

https://api.rsc.org/compounds/v1/filter/smiles

Submit a SMILES as a string via POST. If successful, returns a Query ID representing the search. If not successful, returns an HTTP status other than 200. After running this search, iteratively send the returned Query ID to /filter/{queryId}/status to check the status of the asynchronous query. When the status is 'Complete', send the Query ID to /filter/{queryId}/results to obtain the result.

lookups

Method
Description

GET

lookups-datasources-get

https://api.rsc.org/compounds/v1/lookups/datasources

Many other endpoints let you restrict which sources are used to lookup the requested query. Restricting the sources makes queries faster. To determine which data sources are available, call this endpoint via GET. This endpoint takes no parameters. If successful, returns an array of valid sources as strings. If not successful, returns an HTTP status other than 200.

records

Method
Description

POST

records-batch-post

https://api.rsc.org/compounds/v1/records/batch

Call this POST endpoint with an array of up to 100 Record IDs as integers. The Record ID might have been from one of the /results endpoints. You must supply fields as a JSON-formatted array of strings, representing the information you want to return. The available fields are: SMILES, Formula, InChI, InChIKey, StdInChI, StdInChIKey, AverageMass, MolecularWeight, MonoisotopicMass, NominalMass, CommonName, ReferenceCount, DataSourceCount, PubMedCount, RSCCount, Mol2D, Mol3D. If successful, returns a JSON array of results from the query, with the requested fields. If not successful, returns an HTTP status other than 200.

GET

records-recordId-details-get

https://api.rsc.org/compounds/v1/records/{recordId}/details

Call this endpoint with a Record ID as an integer. The Record ID might have been from one of the /results endpoints. You must have a parameter called 'fields', which contains a comma-separated list of the information you want to return. For example: ?fields=SMILES,Formula,CommonName will return these three fields. The available fields are: SMILES, Formula, InChI, InChIKey, StdInChI, StdInChIKey, AverageMass, MolecularWeight, MonoisotopicMass, NominalMass, CommonName, ReferenceCount, DataSourceCount, PubMedCount, RSCCount, Mol2D, Mol3D. If successful, returns a JSON array of results from the query, with the requested fields. If not successful, returns an HTTP status other than 200.

GET

records-recordId-externalreferences-get

https://api.rsc.org/compounds/v1/records/{recordId}/externalreferences

Submit a recordId. The recordId is a Record ID returned from a /results endpoint. You can optionally supply dataSources as query parameters, representing the data sources to query. You can obtain valid values from the /lookups/datasources endpoint. If dataSources is not specified, all known sources are searched. This will take longer. If successful, returns an array containing external references for the matching ChemSpider record. If not successful, returns an HTTP status other than 200.

GET

records-recordId-image-get

https://api.rsc.org/compounds/v1/records/{recordId}/image

Submit a recordId via GET. The recordId is a Record ID returned from a /results endpoint. If successful, returns a base64-encoded string containing a PNG thumbnail of the structure. If not successful, returns an HTTP status other than 200.

GET

records-recordId-mol-get

https://api.rsc.org/compounds/v1/records/{recordId}/mol

Submit a recordId. The recordId is a Record ID returned from a /results endpoint. If successful, returns a SDF file containing the single record for the matching record. If not successful, returns an HTTP status other than 200.

tools

Method
Description

POST

tools-convert-post

https://api.rsc.org/compounds/v1/tools/convert

Submit an identifier (SMILES, InChI, InChIKey or Mol) as a string called 'input' via POST and return an identifier in another format (SMILES, InChI, InChIKey or Mol). Specify the input format as a string called 'inputFormat', and the output as a string called 'outputFormat'. Allowed conversions: from InChI to InChI Key, from InChI to Mol file, from InChI to SMILES, from InChIKey to InChI, from InChI Key to Mol file, from Mol file to InChI, from Mol file to InChI Key, from SMILES to InChI. If successful, returns a string representing the compound in the requested output format. If not successful, returns an HTTP status other than 200.

POST

tools-validate-inchikey-post

https://api.rsc.org/compounds/v1/tools/validate/inchikey

Submit an InChIKey as a string called 'inchikey' via POST. If successful, returns a boolean value indicating whether the InChIKey is valid. If not successful, returns an HTTP status other than 200.