Skills › Scientific Agent Skills › database-lookup › pubchem.md

pubchem.md

150 lines · skills/database-lookup/references/pubchem.md at 5f2bc03

Open on GitHub

1# PubChem PUG REST API

PubChem PUG REST API

Raw lines 1 to 2

3## Base URL

5```

6https://pubchem.ncbi.nlm.nih.gov/rest/pug

7```

Base URL

https://pubchem.ncbi.nlm.nih.gov/rest/pug

Raw lines 3 to 8

9## URL Pattern

11```

12/{domain}/{namespace}/{identifiers}/{operation}/{output}

13```

15- **domain**: `compound`, `substance`, `assay`

16- **namespace**: `cid`, `name`, `smiles`, `inchi`, `inchikey`, `fastformula`

17- **operation**: `record`, `property`, `synonyms`, `description`, `cids`, `xrefs`

18- **output**: `JSON`, `XML`, `CSV`, `TXT`, `SDF`, `PNG`

URL Pattern

/{domain}/{namespace}/{identifiers}/{operation}/{output}

domain: compound, substance, assay
namespace: cid, name, smiles, inchi, inchikey, fastformula
operation: record, property, synonyms, description, cids, xrefs
output: JSON, XML, CSV, TXT, SDF, PNG

Raw lines 9 to 19

20## Key Endpoints

Key Endpoints

Raw lines 20 to 21

22### Search by name

23```

24GET /compound/name/{name}/JSON

25```

26Example: `/compound/name/aspirin/JSON`

Search by name

GET /compound/name/{name}/JSON

Example: /compound/name/aspirin/JSON

Raw lines 22 to 27

28### Search by CID

29```

30GET /compound/cid/{cid}/JSON

31```

32Example: `/compound/cid/2244/JSON`

34Multiple CIDs: `/compound/cid/2244,5988,3672/JSON`

Search by CID

GET /compound/cid/{cid}/JSON

Example: /compound/cid/2244/JSON

Multiple CIDs: /compound/cid/2244,5988,3672/JSON

Raw lines 28 to 35

36### Search by SMILES

37```

38GET /compound/smiles/{smiles}/JSON

39```

40For SMILES with special characters, use POST:

41```

42POST /compound/smiles/JSON

43Content-Type: application/x-www-form-urlencoded

44smiles=CC(=O)OC1=CC=CC=C1C(=O)O

45```

Search by SMILES

GET /compound/smiles/{smiles}/JSON

For SMILES with special characters, use POST:

POST /compound/smiles/JSON
Content-Type: application/x-www-form-urlencoded
smiles=CC(=O)OC1=CC=CC=C1C(=O)O

Raw lines 36 to 46

47### Search by InChIKey

48```

49GET /compound/inchikey/{inchikey}/JSON

50```

Search by InChIKey

GET /compound/inchikey/{inchikey}/JSON

Raw lines 47 to 51

52### Search by InChI (POST only — InChI strings are too long for URLs)

53```

54POST /compound/inchi/JSON

55Content-Type: application/x-www-form-urlencoded

56inchi=InChI=1S/C9H8O4/...

57```

Search by InChI (POST only — InChI strings are too long for URLs)

POST /compound/inchi/JSON
Content-Type: application/x-www-form-urlencoded
inchi=InChI=1S/C9H8O4/...

Raw lines 52 to 58

59### Search by molecular formula

60```

61GET /compound/fastformula/{formula}/JSON

62```

63Example: `/compound/fastformula/C9H8O4/JSON`

Search by molecular formula

GET /compound/fastformula/{formula}/JSON

Example: /compound/fastformula/C9H8O4/JSON

Raw lines 59 to 64

65### Property retrieval

66```

67GET /compound/{namespace}/{id}/property/{property_list}/JSON

68```

69Properties are comma-separated. Available properties:

71`MolecularFormula`, `MolecularWeight`, `ConnectivitySMILES`, `SMILES`, `InChI`, `InChIKey`, `IUPACName`, `XLogP`, `ExactMass`, `MonoisotopicMass`, `TPSA`, `Complexity`, `Charge`, `HBondDonorCount`, `HBondAcceptorCount`, `RotatableBondCount`, `HeavyAtomCount`, `CID`

73Example:

74```

75/compound/cid/2244/property/MolecularFormula,MolecularWeight,ConnectivitySMILES,IUPACName/JSON

76```

78Response:

79```json

80{

81 "PropertyTable": {

82 "Properties": [

83 {

84 "CID": 2244,

85 "MolecularFormula": "C9H8O4",

86 "MolecularWeight": "180.16",

87 "IUPACName": "2-acetyloxybenzoic acid",

88 "ConnectivitySMILES": "CC(=O)OC1=CC=CC=C1C(O)=O"

89 }

90 ]

91 }

92}

93```

Property retrieval

GET /compound/{namespace}/{id}/property/{property_list}/JSON

Properties are comma-separated. Available properties:

MolecularFormula, MolecularWeight, ConnectivitySMILES, SMILES, InChI, InChIKey, IUPACName, XLogP, ExactMass, MonoisotopicMass, TPSA, Complexity, Charge, HBondDonorCount, HBondAcceptorCount, RotatableBondCount, HeavyAtomCount, CID

Example:

/compound/cid/2244/property/MolecularFormula,MolecularWeight,ConnectivitySMILES,IUPACName/JSON

Response:

{
  "PropertyTable": {
    "Properties": [
      {
        "CID": 2244,
        "MolecularFormula": "C9H8O4",
        "MolecularWeight": "180.16",
        "IUPACName": "2-acetyloxybenzoic acid",
        "ConnectivitySMILES": "CC(=O)OC1=CC=CC=C1C(O)=O"
      }
    ]
  }
}

Raw lines 65 to 94

95### Synonym lookup

96```

97GET /compound/{namespace}/{id}/synonyms/JSON

98```

Synonym lookup

GET /compound/{namespace}/{id}/synonyms/JSON

Raw lines 95 to 99

100### Compound description

101```

102GET /compound/cid/{cid}/description/JSON

103```

104

Compound description

GET /compound/cid/{cid}/description/JSON

Raw lines 100 to 104

105### Get just CIDs from a name

106```

107GET /compound/name/{name}/cids/JSON

108```

109

Get just CIDs from a name

GET /compound/name/{name}/cids/JSON

Raw lines 105 to 109

110### Cross-references (patents, registry IDs)

111```

112GET /compound/cid/{cid}/xrefs/PatentID/JSON

113GET /compound/cid/{cid}/xrefs/RegistryID/JSON

114```

115

Cross-references (patents, registry IDs)

GET /compound/cid/{cid}/xrefs/PatentID/JSON
GET /compound/cid/{cid}/xrefs/RegistryID/JSON

Raw lines 110 to 115

116### Fast similarity search (synchronous CID result)

117```

118POST /compound/fastsimilarity_2d/smiles/cids/JSON

119smiles=CC(=O)OC1=CC=CC=C1C(=O)O&Threshold=90

120```

121

Fast similarity search (synchronous CID result)

POST /compound/fastsimilarity_2d/smiles/cids/JSON
smiles=CC(=O)OC1=CC=CC=C1C(=O)O&Threshold=90

Raw lines 116 to 121

122### 2D structure image

123```

124GET /compound/cid/{cid}/PNG

125GET /compound/cid/{cid}/PNG?image_size=300x300

126```

127

2D structure image

GET /compound/cid/{cid}/PNG
GET /compound/cid/{cid}/PNG?image_size=300x300

Raw lines 122 to 127

128## Rate Limits

129

130- Max **5 requests per second**

131- Max **400 requests per minute**

132- Batch CIDs with commas; use POST when the URL becomes long and keep batches small enough to meet time/payload limits. Endpoint-specific limits differ.

133- Throttle error returns `PUGREST.ServerBusy` fault code

134

Rate Limits

Max 5 requests per second
Max 400 requests per minute
Batch CIDs with commas; use POST when the URL becomes long and keep batches small enough to meet time/payload limits. Endpoint-specific limits differ.
Throttle error returns PUGREST.ServerBusy fault code

Raw lines 128 to 134

135## Error Format

136

137```json

138{

139 "Fault": {

140 "Code": "PUGREST.NotFound",

141 "Message": "No CID found",

142 "Details": ["..."]

143 }

144}

145```

146

147`fastsimilarity_2d` returns `IdentifierList.CID` synchronously; do not look for an

148asynchronous ListKey in a successful fast-search response. Older SMILES property

149aliases may still be accepted but returned JSON keys use the current names above.

150Official contract: https://pubchem.ncbi.nlm.nih.gov/docs/pug-rest

Error Format

{
  "Fault": {
    "Code": "PUGREST.NotFound",
    "Message": "No CID found",
    "Details": ["..."]
  }
}

fastsimilarity_2d returns IdentifierList.CID synchronously; do not look for an asynchronous ListKey in a successful fast-search response. Older SMILES property aliases may still be accepted but returned JSON keys use the current names above. Official contract: https://pubchem.ncbi.nlm.nih.gov/docs/pug-rest

Raw lines 135 to 150