API documentation

This part of the documentation is automatically generated from the ChemSpiPy source code and comments.

chemspipy.api

Core API for interacting with ChemSpider web services.

class chemspipy.ChemSpider[source]

Provides access to the ChemSpider API.

Usage:

>>> from chemspipy import ChemSpider
>>> cs = ChemSpider('<YOUR-SECURITY-TOKEN>')
Parameters:
  • security_token (string) – (Optional) Your ChemSpider security token.
  • user_agent (string) – (Optional) Identify your application to ChemSpider servers.
  • api_url (string) – (Optional) Alternative API server.
get_compound(csid)

Return a Compound object for a given ChemSpider ID. Security token is required.

Parameters:csid (string|int) – ChemSpider ID.
Returns:The Compound with the specified ChemSpider ID.
Return type:Compound
get_compounds(csids)

Return a list of Compound objects, given a list ChemSpider IDs. Security token is required.

Parameters:csids (list[string|int]) – List of ChemSpider IDs.
Returns:List of Compounds with the specified ChemSpider IDs.
Return type:list[Compound]
get_spectrum(spectrum_id)

Return a Spectrum object for a given spectrum ID. Subscriber role security token is required.

Parameters:spectrum_id (string|int) – Spectrum ID.
Returns:The Spectrum with the specified spectrum ID.
Return type:Spectrum
get_spectra(spectrum_ids)

Return a Spectrum object for a given spectrum ID. Subscriber role security token is required.

Parameters:spectrum_ids (list[string|int]) – List of spectrum IDs.
Returns:List of spectra with the specified spectrum IDs.
Return type:list[Spectrum]
get_compound_spectra(csid)

Return Spectrum objects for all the spectra associated with a ChemSpider ID.

Parameters:csid – string|int csid: ChemSpider ID.
Returns:List of spectra for the specified ChemSpider ID.
Return type:list[Spectrum]
get_all_spectra()

Return a full list of Spectrum objects for all spectra in ChemSpider.

Subscriber role security token is required.

Returns:Full list of spectra in ChemSpider.
Return type:list[Spectrum]
search(query, order=None, direction=ASCENDING, raise_errors=False)

Search ChemSpider for the specified query and return the results. Security token is required.

Parameters:
Returns:

Search Results list.

Return type:

Results

Search ChemSpider with arbitrary query.

A maximum of 100 results are returned. Security token is required.

Parameters:query (string) – Search query - a name, SMILES, InChI, InChIKey, CSID, etc.
Returns:List of Compounds.
Return type:list[Compound]
get_record_mol(csid, calc3d=False)

Get ChemSpider record in MOL format. Security token is required.

Parameters:
  • csid (string|int) – ChemSpider ID.
  • calc3d (bool) – Whether 3D coordinates should be calculated before returning record data.
get_original_mol(csid)

Get original submitted MOL file. Security token is required.

Parameters:csid (string|int) – ChemSpider ID.
get_compound_thumbnail(csid)

Get PNG image as binary data.

Parameters:csid (string|int) – ChemSpider ID.
Return type:bytes
get_databases()

Get the list of datasources in ChemSpider.

get_compound_info(csid)

Get SMILES, StdInChI and StdInChIKey for a given CSID. Security token is required.

Parameters:csid (string|int) – ChemSpider ID.
Return type:dict
get_extended_compound_info(csid)

Get extended record details for a CSID. Security token is required.

Parameters:csid (string|int) – ChemSpider ID.
get_extended_compound_info_list(csids)

Get extended record details for a list of CSIDs. Security token is required.

Parameters:csids (list[string|int]) – ChemSpider IDs.
get_extended_mol_compound_info_list(csids, mol_type=MOL2D, include_reference_counts=False, include_external_references=False)

Get extended record details (including MOL) for a list of CSIDs.

A maximum of 250 CSIDs can be fetched per request. Security token is required.

Parameters:
  • csids (list[string|int]) – ChemSpider IDs.
  • mol_type (string) – MOL2D, MOL3D or BOTH.
  • include_reference_counts (bool) – Whether to include reference counts.
  • include_external_references (bool) – Whether to include external references.
get_compound_spectra_info(csid)

Get information about all the spectra for a ChemSpider ID. Subscriber role security token is required.

Parameters:csid (string|int) – ChemSpider ID.
Returns:List of spectrum info.
Return type:list[dict]
get_spectrum_info(spectrum_id)

Get information for a specific spectrum ID. Subscriber role security token is required.

Parameters:spectrum_id (string|int) – spectrum ID.
Returns:Spectrum info.
Return type:dict
get_spectra_info_list(csids)

Get information about all the spectra for a list of ChemSpider IDs.

Parameters:csids (list[string|int]) – ChemSpider IDs.
Returns:List of spectrum info.
Return type:list[dict]
get_all_spectra_info()

Get full list of all spectra in ChemSpider. Subscriber role security token is required.

rtype: list[dict]

request(api, endpoint, **params)

Construct API request and return the XML response.

Parameters:
  • api (string) – The specific ChemSpider API to call (MassSpec, Search, Spectra, InChI).
  • endpoint (string) – ChemSpider API endpoint.
  • params – (Optional) Parameters for the ChemSpider endpoint as keyword arguments.
Return type:

xml tree

construct_api_url(api, endpoint, **params)

Construct a Chemspider API url, encoded, with parameters as a GET querystring.

Parameters:
  • api (string) – The specific ChemSpider API to call (MassSpecAPI, Search, Spectra, InChI).
  • endpoint (string) – ChemSpider API endpoint.
  • params – (Optional) Parameters for the ChemSpider endpoint as keyword arguments.
Return type:

string

Search ChemSpider with arbitrary query, returning results in order of the best match found.

This method returns a transaction ID which can be used with other methods to get search status and results.

Security token is required.

Parameters:query (string) – Search query - a name, SMILES, InChI, InChIKey, CSID, etc.
Returns:Transaction ID.
Return type:string
async_simple_search_ordered(query, order=CSID, direction=ASCENDING)

Search ChemSpider with arbitrary query, returning results with a custom order.

This method returns a transaction ID which can be used with other methods to get search status and results.

Security token is required.

Parameters:
Returns:

Transaction ID.

Return type:

string

get_async_search_status(rid)

Check the status of an asynchronous search operation.

Security token is required.

Parameters:rid (string) – A transaction ID, returned by an asynchronous search method.
Returns:Unknown, Created, Scheduled, Processing, Suspended, PartialResultReady, ResultReady, Failed, TooManyRecords
Return type:string
get_async_search_status_and_count(rid)

Check the status of an asynchronous search operation. If ready, a count and message are also returned.

Security token is required.

Parameters:rid (string) – A transaction ID, returned by an asynchronous search method.
Return type:dict
get_async_search_result(rid)

Get the results from a asynchronous search operation. Security token is required.

Parameters:rid (string) – A transaction ID, returned by an asynchronous search method.
Returns:A list of Compounds.
Return type:list[Compound]
get_async_search_result_part(rid, start=0, count=-1)

Get a slice of the results from a asynchronous search operation. Security token is required.

Parameters:
  • rid (string) – A transaction ID, returned by an asynchronous search method.
  • start (int) – The number of results to skip.
  • count (int) – The number of results to return. -1 returns all through to end.
Returns:

A list of Compounds.

Return type:

list[Compound]

simple_search_by_formula(formula)

Search ChemSpider by molecular formula.

Parameters:formula (string) – Molecular formula
Returns:A list of Compounds.
Return type:list[Compound]
simple_search_by_mass(mass, mass_range)

Search ChemSpider by mass +/- range.

Parameters:
  • mass (float) – The mass to search for.
  • mass_range (float) – The +/- mass range to allow.
Returns:

A list of Compounds.

Return type:

list[Compound]

chemspipy.api.MOL2D = u'2d'

2D coordinate dimensions

chemspipy.api.MOL3D = u'3d'

3D coordinate dimensions

chemspipy.api.BOTH = u'both'

Both coordinate dimensions

chemspipy.api.ASCENDING = u'ascending'

Ascending sort direction

chemspipy.api.DESCENDING = u'descending'

Descending sort direction

chemspipy.api.CSID = u'csid'

CSID sort order

chemspipy.api.MASS_DEFECT = u'mass_defect'

Mass defect sort order

chemspipy.api.MOLECULAR_WEIGHT = u'molecular_weight'

Molecular weight sort order

chemspipy.api.REFERENCE_COUNT = u'reference_count'

Reference count sort order

chemspipy.api.DATASOURCE_COUNT = u'datasource_count'

Datasource count sort order

chemspipy.api.PUBMED_COUNT = u'pubmed_count'

Pubmed count sort order

chemspipy.api.RSC_COUNT = u'rsc_count'

RSC count sort order

chemspipy.objects

Objects returned by ChemSpiPy API methods.

class chemspipy.Compound[source]

A class for retrieving and caching details about a specific ChemSpider record.

The purpose of this class is to provide access to various parts of the ChemSpider API that return information about a compound given its ChemSpider ID. Information is loaded lazily when requested, and cached for future access.

Parameters:
  • cs (ChemSpider) – ChemSpider session.
  • csid (int|string) – ChemSpider ID.
csid

ChemSpider ID.

image_url

Return the URL of a PNG image of the 2D chemical structure.

molecular_formula

Return the molecular formula for this Compound.

Return type:string
smiles

Return the SMILES for this Compound.

Return type:string
stdinchi

Return the Standard InChI for this Compound.

Return type:string
stdinchikey

Return the Standard InChIKey for this Compound.

Return type:string
inchi

Return the InChI for this Compound.

Return type:string
inchikey

Return the InChIKey for this Compound.

Return type:string
average_mass

Return the average mass of this Compound.

Return type:float
molecular_weight

Return the molecular weight of this Compound.

Return type:float
monoisotopic_mass

Return the monoisotopic mass of this Compound.

Return type:float
nominal_mass

Return the nominal mass of this Compound.

Return type:float
alogp

Return the calculated AlogP for this Compound.

Return type:float
xlogp

Return the calculated XlogP for this Compound.

Return type:float
common_name

Return the common name for this Compound.

Return type:string
mol_2d

Return the MOL file for this Compound with 2D coordinates.

Return type:string
mol_3d

Return the MOL file for this Compound with 3D coordinates.

Return type:string
mol_raw

Return unprocessed MOL file for this Compound.

Return type:string
image

Return a 2D depiction of this Compound.

Return type:bytes
spectra

Return all the available spectral data for this Compound.

Return type:list[Spectrum]
class chemspipy.Spectrum[source]

A class for retrieving and caching details about a Spectrum.

Initializing a Spectrum from a spectrum ID requires a subscriber role security token.

Parameters:
  • cs (ChemSpider) – ChemSpider session.
  • spectrum_id (int|string) – Spectrum ID.
classmethod from_info_dict(cs, info)[source]

Initialize a Spectrum from an info dict that has already been retrieved.

spectrum_id

Spectrum ID.

Return type:int
csid

ChemSpider ID of related compound.

Return type:int
spectrum_type

Spectrum type.

Possible values include HNMR, CNMR, IR, UV-Vis, NIR, EI, 2D1H1HCOSY, 2D1H13CD, APCI+, R, MALDI+, 2D1H13CLR, APPI-, CI+ve, ESI+, 2D1H1HOESY, FNMR, CI-ve, ESI-, PNMR.

Return type:string
file_name

Spectrum file name.

Return type:string
comments

Spectrum comments. Can be None.

Return type:string
url

Spectrum URL.

Return type:string
data

Spectrum data file contents. Requires an additional request. Result is cached.

Return type:string
original_url

Original spectrum URL. Can be None.

Return type:string
submitted_date

Spectrum submitted date.

Return type:datetime.datetime
class chemspipy.Results[source]

Container class to perform a search on a background thread and hold the results when ready.

Generally shouldn’t be instantiated directly. See search() instead.

Parameters:
  • cs (ChemSpider) – ChemSpider session.
  • searchfunc (function) – Search function that returns a transaction ID.
  • searchargs (tuple) – Arguments for the search function.
  • raise_errors (bool) – If True, raise exceptions. If False, store on exception property.
  • max_requests (int) – Maximum number of times to check if search results are ready.
ready()[source]

Return True if the search finished.

Return type:bool
success()[source]

Return True if the search finished with no errors.

Return type:bool
wait()[source]

Block until the search has completed and optionally raise any resulting exception.

status

Current status string returned by ChemSpider.

Returns:‘Unknown’, ‘Created’, ‘Scheduled’, ‘Processing’, ‘Suspended’, ‘PartialResultReady’, ‘ResultReady’
Return type:string
exception

Any Exception raised during the search. Blocks until the search is finished.

message

A contextual message about the search. Blocks until the search is finished.

Return type:string
count

The number of search results. Blocks until the search is finished.

Return type:int
duration

The time taken to perform the search. Blocks until the search is finished.

Return type:datetime.timedelta

chemspipy.errors

Exceptions raised by ChemSpiPy.

exception chemspipy.errors.ChemSpiPyError[source]

Root ChemSpiPy Exception.

exception chemspipy.errors.ChemSpiPyParseError[source]

Raised when ChemSpiPy fails to parse a response from the ChemSpider servers.

exception chemspipy.errors.ChemSpiPyAuthError[source]

Raised when the security token doesn’t have access to an endpoint.

exception chemspipy.errors.ChemSpiPyNotFoundError[source]

Raised when no record is present for the requested CSID.

exception chemspipy.errors.ChemSpiPyTimeoutError[source]

Raised when an asynchronous request times out.

exception chemspipy.errors.ChemSpiPyServerError[source]

Raised when ChemSpider returns a 500 status code with an error message.