MangroveNP v0.6

数据接口 / API

中文

MangroveNP 不运行服务器端程序：网站只提供静态文件，所有数据以普通文件形式公开，无需注册或密钥。检索、筛选、分页与结构检索均在浏览器中计算。所有数据以 CC BY 4.0 发布，使用时请按"如何引用"页署名。

• 基础地址：即将公布
• 只接受 GET 与 HEAD 请求；跨域预检 OPTIONS 返回 204。
• /data/ 下的文件允许跨域访问（Access-Control-Allow-Origin: *，Access-Control-Allow-Methods: GET, HEAD）。
• 带哈希的文件名（形如 <名称>.<sha12>.<扩展名>）随每次构建而变化，请始终通过对应的清单文件（manifest）获取当前文件名。
• /api/ 下的路径均已停用并返回 404，唯一例外是旧的结构图地址 /api/database/compounds/{id}/structure.svg，仍可访问（内容同 /data/svg/{id}.svg）。
• 不存在的路径返回 404 页面；超出访问频率限制时返回 HTTP 429（见第 6 节）。

{id} 为 MangroveNP 记录号，格式为 mangrove- 加数字。

1. 文件与路径

2. 下载文件

均位于 /data/，缓存 public, max-age=3600。

字段说明见"数据字典"页；校验方法见"帮助"页。

3. JSON 结构

/data/db/db-manifest.json

{schema, release, index, sha256, records, recordsPath}：index 为当前索引文件名（db-index.<sha12>.json），sha256 为其校验值，records 为记录数，recordsPath 为详情文件路径格式（records/<id>.json）。

/data/db/db-index.<sha12>.json

{schema, release, license, notice, stats, taxa, fields, rows}

• stats：{scope, release, license, builtAt, records, uniqueInchikeys, occurrences, sources}；sources 为 [{name, records}]，按结构来源（structure_from）计数，一条记录可同时计入两个来源。
• taxa：{scope, taxa}；taxa 为 [{taxon, occurrences, records}]。
• fields：rows 中各列的名称：id、name、formula、smiles、inchikey、structure_from、taxa、occurrenceCount、isomeric_smiles、search、structRow、organismTypeMask、structureCaution。
• rows：每条记录一个数组，顺序同 fields。taxa 为生物名称列表；search 为小写的检索文本；structRow 为该记录在结构检索元数据中的行号；organismTypeMask 为来源生物类型的位掩码（类型顺序见 struct-manifest 的 organismTypes）；structure_from 列为字符串数组，不为空。
• 交叉引用数据库（also_listed_in）不在概况与列表中出现，只出现在单条记录详情和下载文件中。

/data/db/records/{id}.json

{id, structureFrom, recordId, name, formula, smiles, inchiKey, taxa, occurrenceCount, license, alsoListedIn, structureCaution, identifiers, metadata, occurrences}

• structureFrom：结构来源，字符串数组（元素为 COCONUT、LOTUS 或 OPSIN，不为空）；alsoListedIn：交叉引用数据库，字符串数组，没有时为 []，仅作交叉引用。多个值只在 CSV 中以 ; 连接。
• taxa：该记录的全部物种（不截断）。
• identifiers：外部标识符字段（inchikey、ik_mangrove_ids、候选 CAS 各字段、cid_primary、cid_all_exact_ik、multi_cid、wikidata_qid、chebi_id）。
• metadata：公开结构层的完整记录（不含 evidence、species、dois），包括 inchi、structure_from、also_listed_in 与 structure_provenance，字段格式同下载的 JSON 文件。
• occurrences：[{taxon, status, metadata}]，status 为 literature_evidence，metadata 为 {doi, pmid, plantPart, organismType}。pmid 用于生成 PubMed 链接，没有时为空字符串。

/data/struct/struct-manifest.json

{schema, release, builtAt, source, sourceSha256, rdkitjs, records, structures, organismTypes, morgan, fields, files}：rdkitjs 为 RDKit.js 版本；records 为记录数（6,234），structures 为唯一结构数（5,773）；morgan 为 {radius: 2, nBits: 2048}；files 列出 struct-meta、morgan2048、sslib-pattern、struct-props 四个文件的 {file, sha256, bytes}。

• struct-meta：rows 每行为 [id, otherIds 或 0, name, inchikey, canonicalSmiles, formula, organismTypeMask]，每个唯一 InChIKey 一行；rows 以外的头部键与 struct-manifest.json 相同（不含 files）：schema, release, builtAt, source, sourceSha256, rdkitjs, records, structures, organismTypes, morgan, fields。id 为该 InChIKey 中记录号最小的记录，otherIds 为具有同一 InChIKey 的其他记录（升序）或 0；canonicalSmiles 一项在 fields 中名为 smiles，是该记录 isomeric_smiles 经 RDKit.js 规范化后的 SMILES（保留立体与同位素）。
• morgan2048：每行 256 字节的 Morgan 指纹（半径 2，2,048 位）；每个字节内低位在前，第 k 位为 (byte[k>>3] >> (k&7)) & 1；行顺序与 struct-meta 的 rows 相同（每个唯一 InChIKey 一行，共 5,773 行，按 InChIKey 字节序升序；sslib-pattern 与 struct-props 也按此顺序）。浏览器中的相似性检索用这些指纹计算 Tanimoto 相似度，返回 Tanimoto ≥ 0.6（含 0.6）的结构；阈值默认 0.6，可在 0.30–0.90 之间以 0.05 为步长调整；超出范围的阈值按边界值处理。
• sslib-pattern：每行为 2 字节长度（小端 uint16）加 RDKit SubstructLibrary pattern 指纹数据。
• struct-props：{schema, source, order, columns, cols, npclassifier}，其中 source 为两个来源文件路径的数组 ["data/mangrovenp-v0.6-descriptors.tsv","data/mangrovenp-v0.6-npclassifier.tsv"]；order 为字符串 "struct-meta rows"；columns 为对象，把 cols 中各简称对应到 descriptors.tsv 的列名：{mw:"mw_average", mwExact:"mw_exact", logp:"logp_crippen", tpsa:"tpsa", hbd:"hbd", hba:"hba", rotb:"rotatable_bonds", lipv:"lipinski_violations", heavy:"heavy_atoms", rings:"ring_count", fsp3:"fsp3", npl:"np_likeness"}（veber 不在其中，取自 descriptors.tsv 的 veber_pass，为 0/1）；cols 含 mw、mwExact、logp、tpsa、hbd、hba、rotb、lipv、heavy、rings、fsp3、npl、veber；npclassifier 含类别词表与每行的 pathway / superclass / class / 是否糖苷编码（整数、整数数组表示多个类别，-1 表示无）。

/data/npclassifier/npc-browse.json

{schema, source, records, levels, unclassified, notFurtherClassified, note_zh, note_en, nodes}：levels 为 pathway、superclass、class；nodes 为 [{level, label, parent, records}]，records 为记录数（以 6,234 条公开记录计）。有多个类别的记录在其每个类别下各计一次；无类别的记录归入「未分类 / Unclassified」。parent 为从最高一级起的上级类别名数组：pathway 为 []，superclass 为 [pathway]，class 为 [pathway, superclass]。source 为 {labels_flat, sha256, npclassifier_tsv}；顶层 records 为公开记录数（6,234）；unclassified 与 notFurtherClassified 分别给出「未分类 / Unclassified」与「未细分 / Not further classified」的中英文标签；无其他键。

/data/errata/tombstones.json

{schema, release, source, records}：release 为 "MangroveNP v0.6"；source 为 {file, sha256}；records 为 [{record_id, name, removed_in_version, reason_en, reason_zh}]，列出已撤回的记录；不含结构、SMILES、InChIKey 或分子式。

4. 永久链接

• /compound/mangrove-XXXX：公开记录的永久链接，打开该记录的页面。
• 已撤回记录的链接打开说明页，显示记录号、名称、撤回版本与原因，不显示旧结构。
• 未知记录号返回 404。

5. 检索参数（在浏览器中处理）

网站检索页面在浏览器中按以下参数筛选和分页，参数名与旧接口相同并有新增。参数写在网址的 #database? 之后（路径为 /），例如 /#database?q=luteolin&org=plant&mwmin=200&mwmax=400。

不支持的参数返回 {error: "Unsupported parameter"}。检索结果对象为 {total, page, limit, scope, notice, records}，每条为 {id, structureFrom, recordId, name, formula, smiles, inchiKey, taxa（最多 6 个）, occurrenceCount, license}，其中 structureFrom 为字符串数组，不为空。导出也在浏览器中生成，"导出全部筛选结果"包含全部匹配记录。

6. 访问频率限制

服务器按 IP 地址限制请求频率：每秒 30 次，允许 40–60 次的短时突发；SDF、SMI 与两个 TSV 下载文件（描述符表与 NPClassifier 分类表）另限为每秒 2 次，突发 4 次；超出时返回 HTTP 429。批量使用请直接下载完整数据文件，不要逐条抓取。

7. 版本与稳定性

接口版本与兼容性安排：当前为 v0.6 静态接口，字段变更记录在变更日志中。

English

MangroveNP runs no server-side program: the website serves static files only, and all data are published as plain files; no registration or key is needed. Search, filtering, paging and structure search are computed in your browser. All data are released under CC BY 4.0; please give credit as described on the How to cite page.

• Base URL: Coming soon
• Only GET and HEAD requests are accepted; cross-origin preflight OPTIONS returns 204.
• Files under /data/ allow cross-origin access (Access-Control-Allow-Origin: *, Access-Control-Allow-Methods: GET, HEAD).
• Hashed file names (of the form <name>.<sha12>.<ext>) change with every build; always resolve the current name through the corresponding manifest.
• All paths under /api/ are retired and return 404, with one exception: the old structure image URL /api/database/compounds/{id}/structure.svg is still served (same content as /data/svg/{id}.svg).
• Paths that do not exist return the 404 page; requests over the rate limit return HTTP 429 (see section 6).

{id} is a MangroveNP record ID: mangrove- followed by digits.

1. Files and paths

2. Download files

All under /data/, cached public, max-age=3600.

See the Data dictionary page for field descriptions and the Help page for how to check checksums.

3. JSON structures

/data/db/db-manifest.json

{schema, release, index, sha256, records, recordsPath}: index is the current index file name (db-index.<sha12>.json), sha256 its checksum, records the number of records and recordsPath the path pattern of the detail files (records/<id>.json).

/data/db/db-index.<sha12>.json

{schema, release, license, notice, stats, taxa, fields, rows}

• stats: {scope, release, license, builtAt, records, uniqueInchikeys, occurrences, sources}; sources is [{name, records}], counted by structure source (structure_from); a record can count under two sources.
• taxa: {scope, taxa}; taxa is [{taxon, occurrences, records}].
• fields: names of the columns in rows: id, name, formula, smiles, inchikey, structure_from, taxa, occurrenceCount, isomeric_smiles, search, structRow, organismTypeMask, structureCaution.
• rows: one array per record, in fields order. taxa is a list of organism names; search is the lower-cased search text; structRow is the record's row in the structure-search metadata; organismTypeMask is a bitmask of source organism types (order given by organismTypes in the struct manifest); the structure_from column is an array of strings, never empty.
• Cross-reference databases (also_listed_in) do not appear in the overview or the list; they appear only in the per-record detail files and the download files.

/data/db/records/{id}.json

{id, structureFrom, recordId, name, formula, smiles, inchiKey, taxa, occurrenceCount, license, alsoListedIn, structureCaution, identifiers, metadata, occurrences}

• structureFrom: structure source, an array of strings (elements COCONUT, LOTUS or OPSIN; never empty); alsoListedIn: cross-reference databases, an array of strings, [] when there is none, for cross-reference only. Multiple values are joined with ; only in the CSV.
• taxa: all species of the record (not truncated).
• identifiers: the external identifier fields (inchikey, ik_mangrove_ids, the candidate CAS fields, cid_primary, cid_all_exact_ik, multi_cid, wikidata_qid, chebi_id).
• metadata: the full public structure layer record (without evidence, species and dois), including inchi, structure_from, also_listed_in and structure_provenance, in the same format as the JSON download.
• occurrences: [{taxon, status, metadata}], with status = literature_evidence and metadata = {doi, pmid, plantPart, organismType}. pmid is used to build PubMed links and is an empty string when there is none.

/data/struct/struct-manifest.json

{schema, release, builtAt, source, sourceSha256, rdkitjs, records, structures, organismTypes, morgan, fields, files}: rdkitjs is the RDKit.js version; records is the number of records (6,234) and structures the number of unique structures (5,773); morgan is {radius: 2, nBits: 2048}; files gives {file, sha256, bytes} for struct-meta, morgan2048, sslib-pattern and struct-props.

• struct-meta: each row of rows is [id, otherIds or 0, name, inchikey, canonicalSmiles, formula, organismTypeMask], one row per unique InChIKey; the header keys other than rows are the same as in struct-manifest.json without files: schema, release, builtAt, source, sourceSha256, rdkitjs, records, structures, organismTypes, morgan, fields. id is the record with the lowest record number for that InChIKey, and otherIds lists the other records with the same InChIKey (ascending) or is 0; the canonicalSmiles item is named smiles in fields and is the RDKit.js canonical SMILES of that record's isomeric_smiles (stereo and isotopes kept).
• morgan2048: a 256-byte Morgan fingerprint (radius 2, 2,048 bits) per row; within each byte the lowest bit comes first, so bit k is (byte[k>>3] >> (k&7)) & 1; rows are in the same order as struct-meta rows (one row per unique InChIKey, 5,773 rows, InChIKey ascending in byte order; sslib-pattern and struct-props use the same order). Similarity search in your browser computes Tanimoto similarity on these fingerprints and returns structures with Tanimoto ≥ 0.6 (0.6 included). The threshold defaults to 0.6 and can be set from 0.30 to 0.90 in steps of 0.05; a threshold outside this range is treated as the nearest boundary value.
• sslib-pattern: per row, a 2-byte length (little-endian uint16) followed by RDKit SubstructLibrary pattern-fingerprint data.
• struct-props: {schema, source, order, columns, cols, npclassifier}; source is an array of the two source file paths, ["data/mangrovenp-v0.6-descriptors.tsv","data/mangrovenp-v0.6-npclassifier.tsv"]; order is the string "struct-meta rows"; columns is an object mapping each short name in cols to its descriptors.tsv column: {mw:"mw_average", mwExact:"mw_exact", logp:"logp_crippen", tpsa:"tpsa", hbd:"hbd", hba:"hba", rotb:"rotatable_bonds", lipv:"lipinski_violations", heavy:"heavy_atoms", rings:"ring_count", fsp3:"fsp3", npl:"np_likeness"} (veber has no entry; it is 0/1 from descriptors.tsv veber_pass); cols holds mw, mwExact, logp, tpsa, hbd, hba, rotb, lipv, heavy, rings, fsp3, npl and veber; npclassifier holds the class vocabularies and per-row pathway / superclass / class / glycoside codes (an integer, an integer array for several classes, or -1 for none).

/data/npclassifier/npc-browse.json

{schema, source, records, levels, unclassified, notFurtherClassified, note_zh, note_en, nodes}: levels is pathway, superclass, class; nodes is [{level, label, parent, records}], where records is a record count (on the basis of the 6,234 public records). A record with several labels is counted under each of them; records without a label are shown under 「未分类 / Unclassified」. parent is the array of ancestor labels from the top: [] for pathway, [pathway] for superclass, [pathway, superclass] for class. source is {labels_flat, sha256, npclassifier_tsv}; the top-level records is the number of public records (6,234); unclassified and notFurtherClassified give the Chinese and English labels 「未分类 / Unclassified」 and 「未细分 / Not further classified」; there are no other keys.

/data/errata/tombstones.json

{schema, release, source, records}: release is "MangroveNP v0.6"; source is {file, sha256}; records is [{record_id, name, removed_in_version, reason_en, reason_zh}] for the withdrawn records; it contains no structure, SMILES, InChIKey or formula.

4. Permanent links

• /compound/mangrove-XXXX: permanent link of a public record; opens that record's page.
• A link to a withdrawn record opens a notice page showing the record ID, name, the release in which it was withdrawn and the reason, without the old structure.
• Unknown record IDs return 404.

5. Search parameters (handled in your browser)

The site's search page filters and pages records in your browser using the parameters below; the names are the same as in the old interface, plus new ones. They appear in the page address after #database? (the path is /), for example /#database?q=luteolin&org=plant&mwmin=200&mwmax=400.

An unsupported parameter returns {error: "Unsupported parameter"}. The result object is {total, page, limit, scope, notice, records}, each record being {id, structureFrom, recordId, name, formula, smiles, inchiKey, taxa (up to 6), occurrenceCount, license}; structureFrom is an array of strings, never empty. Exports are also built in your browser; "export all filtered" covers every matching record.

6. Rate limits

Requests are rate-limited per IP address: 30 per second, with short bursts of 40–60 allowed; downloads of the SDF, the SMI and the two TSV files (descriptors and NPClassifier) are further limited to 2 per second, with a burst of 4; requests above the limit receive HTTP 429. For bulk use, please download the full data files instead of fetching files one by one.

7. Versioning and stability

Interface versioning and compatibility: The current interface is the v0.6 static API; field changes are recorded in the changelog.

数据许可：CC BY 4.0 · Data licence: CC BY 4.0 — 许可与引用 · License & citation

返回首页 · Back to home