Responses

TypedDict definitions for PubChem PUG-REST and PUG-View API responses.

This module provides a single source of truth for the JSON response shapes returned by the PubChem REST APIs.

Structure overview¶

PubChem responses follow two broad envelope shapes depending on the endpoint:

InformationList envelope (PUG-REST /annotations/headings and /annotations/sourcename):

{
"InformationList": {
    "Annotation": [ ... ]
    }
}

Annotations envelope (PUG-View /annotations/heading):

{
    "Annotations": {
        "Annotation": [ ... ],
        "Page": 1,
        "TotalPages": 42
    }
}

Within both envelopes each Annotation element is an AnnotationEntry. When the entry was fetched via PUG-View (i.e. a specific heading), it additionally carries a Data list whose elements are PubChemDatum records containing the deposited values.

Hierarchy¶

The nesting from outermost to innermost is:

InformationListEnvelope / AnnotationsEnvelope
    └── AnnotationEntry
        ├── LinkedRecords
        └── Data
                └── PubChemDatum
                    ├── DatumValue
                    │     └── StringWithMarkup
                    └── ExtendedReference
                            └── MatchedRecord

All classes use total=False where keys are optional in the real API responses, and total=True (the default) where keys are always present.

`AnnotationEntry` ¶

Bases: TypedDict

A single annotation record returned by the PubChem PUG-REST or PUG-View API.

This type covers both the lightweight form returned by /annotations/headings (which carries only Type and Heading) and the full form returned by /annotations/heading/<heading> (which additionally carries Data, LinkedRecords, SourceID, etc.).

Using total=False throughout reflects that the set of keys present varies significantly by endpoint and depositor.

`ANID` ¶

PubChem Annotation Identifier, a unique integer assigned to this annotation record.

`Data` ¶

The list of individual deposited data points. Present only for entries fetched via a specific heading endpoint.

`Description` ¶

Free-text description lines provided by the depositor.

`Heading` ¶

The specific annotation heading name (e.g. "Dissociation Constants", "Boiling Point").

`LinkedRecords` ¶

Identifiers linking this entry to PubChem compound, substance, and assay records.

`Name` ¶

The name of the compound or entity this annotation describes.

`Reference` ¶

Citation strings provided by the depositor.

`SourceID` ¶

The depositor's own identifier for this record (e.g. a database accession number). Cast to int where a numeric ID is expected.

`SourceName` ¶

The human-readable name of the depositing organization.

`Type` ¶

The broad category of this annotation heading (e.g. "Compound", "Gene", "Assay").

`URL` ¶

A URL provided by the depositor pointing to the original source.

`AnnotationsEnvelope` ¶

Bases: TypedDict

Top-level envelope for PUG-View responses that wrap an Annotations list.

Returned by endpoints such as:

/rest/pug_view/annotations/heading/<heading>/JSON

`Annotations` ¶

The inner object containing the annotation list and optional pagination metadata.

`DatumValue` ¶

Bases: TypedDict

The Value object on a single data point within an annotation.

PubChem data points can carry several value types (numeric, boolean, binary). This class models only the StringWithMarkup variant, which is the form used for textual property data such as pKa strings.

`StringWithMarkup` ¶

A list of string value containers. In practice this list contains exactly one element for property annotations.

`ExtendedReference` ¶

Bases: TypedDict

A single element of the ExtendedReference list on a datum.

Provides cross-references from a deposited data point to other PubChem record types. The Matched key is present only when PubChem has successfully linked the value to a live data record.

`Matched` ¶

The matched record containing the PCLID, if available.

`InformationListEnvelope` ¶

Bases: TypedDict

Top-level envelope for PUG-REST responses that wrap an InformationList.

Returned by endpoints such as:

/rest/pug/annotations/headings/JSON
/rest/pug/annotations/sourcename/<source>/JSON

`InformationList` ¶

The inner object containing the annotation list and optional pagination metadata.

`LinkedRecords` ¶

Bases: TypedDict

The LinkedRecords object on a PubChem annotation entry.

Maps PubChem record type names to lists of integer identifiers for all records that are linked to this annotation entry. Additional record types beyond those listed here (e.g. SID, AID) may be present in real responses but are not modelled here.

`AID` ¶

List of PubChem Assay Identifiers linked to this entry.

`CID` ¶

List of PubChem Compound Identifiers linked to this entry. Typically contains exactly one element for compound annotations.

`SID` ¶

List of PubChem Substance Identifiers linked to this entry.

`MatchedRecord` ¶

Bases: TypedDict

The Matched sub-object within an ExtendedReference entry.

Carries identifiers that link a specific deposited value to its corresponding record in PubChem's live data system.

`PCLID` ¶

PubChem Live Data Identifier. Links the measurement to its canonical record. Not present for all depositors.

`PubChemDatum` ¶

Bases: TypedDict

A single data point within a PubChem PUG-View annotation entry.

Each AnnotationEntry fetched from a specific heading contains a Data list whose elements are PubChemDatum records. Each datum represents one deposited measurement or value from a single source.

`ExtendedReference` ¶

Cross-references linking this datum to other PubChem record types. Used to recover the PCLID when present.

`Value` ¶

The deposited value, in StringWithMarkup form for textual properties.

`StringWithMarkup` ¶

Bases: TypedDict

A single element of the StringWithMarkup list on a datum value.

PubChem wraps all deposited string values in this container, which in the full API response can also carry markup annotations (bold, italic, subscript, etc.). Only the plain string is modelled here since markup is not used by this package.

`String` ¶

The plain text content of the deposited value.

`_AnnotationsList` ¶

Bases: TypedDict

The inner Annotations object in a PUG-View response.

`Annotation` ¶

The list of annotation records.

`Page` ¶

The current page number when paginated results are returned.

`TotalPages` ¶

The total number of available pages.

`_InformationList` ¶

Bases: TypedDict

The inner InformationList object in a PUG-REST response.

`Annotation` ¶

The list of annotation records.

`Page` ¶

The current page number when paginated results are returned.

`TotalPages` ¶

The total number of available pages.

Responses

Structure overview¶

Hierarchy¶

AnnotationEntry ¶

ANID ¶

Data ¶

Description ¶

Heading ¶

LinkedRecords ¶

Name ¶

Reference ¶

SourceID ¶

SourceName ¶

Type ¶

URL ¶

AnnotationsEnvelope ¶

Annotations ¶

DatumValue ¶

StringWithMarkup ¶

ExtendedReference ¶

Matched ¶

InformationListEnvelope ¶

InformationList ¶

LinkedRecords ¶

AID ¶

CID ¶

SID ¶

MatchedRecord ¶

PCLID ¶

PubChemDatum ¶

ExtendedReference ¶

Value ¶

StringWithMarkup ¶

String ¶

_AnnotationsList ¶

Annotation ¶

Page ¶

TotalPages ¶

_InformationList ¶

Annotation ¶

Page ¶

TotalPages ¶

`AnnotationEntry` ¶

`ANID` ¶

`Data` ¶

`Description` ¶

`Heading` ¶

`LinkedRecords` ¶

`Name` ¶

`Reference` ¶

`SourceID` ¶

`SourceName` ¶

`Type` ¶

`URL` ¶

`AnnotationsEnvelope` ¶

`Annotations` ¶

`DatumValue` ¶

`StringWithMarkup` ¶

`ExtendedReference` ¶

`Matched` ¶

`InformationListEnvelope` ¶

`InformationList` ¶

`LinkedRecords` ¶

`AID` ¶

`CID` ¶

`SID` ¶

`MatchedRecord` ¶

`PCLID` ¶

`PubChemDatum` ¶

`ExtendedReference` ¶

`Value` ¶

`StringWithMarkup` ¶

`String` ¶

`_AnnotationsList` ¶

`Annotation` ¶

`Page` ¶

`TotalPages` ¶

`_InformationList` ¶

`Annotation` ¶

`Page` ¶

`TotalPages` ¶