Help:Use Data From External System

< Help Top

  English |  日本語  

Use of Data from External Systems by means of API

"Application Programming Interface" (API) is an IT term that refers to commands, functions, and program procedures that are required for software development. Metabolonote provides several types of APIs. By utilizing these APIs from external programs (other databases and applications), users can directly access metadata managed by the Metabolonote system without using a browser.

For example, by reformatting metadata information you obtained from Metabolonote using the metadata IDs, you can display the Metabolonote metadata information on your own database.

API is one of the most important Metabolonote functions. We will develop a wide variety of APIs, including search functions.

Introductions

The RESTful format, where parameters are described in the URL formula, is adopted for the Metabolonote API. Through HTTP access to the URL formula created in accordance with those parameters, the result is returned to the client in text format.

Format

The base URL that provides API is described below.

http://metabolonote.kazusa.or.jp/mnapi.php

Describe the following parameters that are Action name (API name) passed to mnapi.php, and set(s) of key and value of the parameter for the action as shown below.

http://metabolonote.kazusa.or.jp/mnapi.php?action=Action name&key１=value１&key２=value２

(Example)
http://metabolonote.kazusa.or.jp/mnapi.php?action=getDataByMetadataId&id=SE1_S01_M01_D01&output=txt

Returned Value

Data is returned in text format.

Metadata Field Name

In the text data returned, the Metablonote metadata layer (SE, S, M, D, etc.) and the field name (Title, Description, etc.) are expressed with lower-case characters and underscores as shown below.

(Example）

SE -> sample_set
Instrument Type -> instrument_type

This expression format is based on the element and attribute names of the XML schema definition of the Togo Metabolome Data Format (TogoMD) we defined. See here for details about all correspondence relationships.

Error

If an API error occurs, the first line of the text that is returned is prefixed with "MN_ERROR".

(Example) The example below shows the URL with an error.
http://metabolonote.kazusa.or.jp/mnapi.php?action=getDataByMetadataId&id=SA1

MN_ERROR
The specified page does not exist

APIs for Obtaining Data

getDataByMetadataId

Action name	getDataByMetadataId
Description	Obtains metadata based on the metadata ID. You can select the data output format from the tab-separated text (txt) format and the XML (xml) format.
Prameter
Key	Description	Value	Essential/Not essential	Default value
id	Target Metadata ID	Metadata ID	Essential
output	Specifies the output format	txt or xml	Not essential	txt
mode	Specifies the layers to output	all, single or related	Not essential	all
Sample
https://metabolonote.jp/mnapi.php?action=getDataByMetadataId&id=SE1_S01 https://metabolonote.jp/mnapi.php?action=getDataByMetadataId&id=SE1_S01_M01_D01&output=txt https://metabolonote.jp/mnapi.php?action=getDataByMetadataId&id=SE1_MS1&output=xml https://metabolonote.jp/mnapi.php?action=getDataByMetadataId&id=SE1_S01_M01_D01&output=txt&mode=single https://metabolonote.jp/mnapi.php?action=getDataByMetadataId&id=SE1_S01_M01&output=xml&mode=related

Parameters

id

This specifies the ID of each layer connected with underscores. Notice that this has a different format from that of the page name of Metabolonote.

id:       SE1_S01_M01_D01   <- Use this ID
Page name: SE1:/S01/M01/D01

See here for details about how ID is handled by Metabolonote.

output

You can select the tab-separated text (txt) format or the XML (xml) format.

txt: Tab-separated text format

• First line

#	id	kazusa:SE1_S01.info.txt

#[tab]id[tab][system identifier]:[Metadata ID].info.txt

[tab]: Tab control character
[system identifier]: Characters assigned to each individual Metabolonote system in order to distinguish which Metabolonote system the data is originated from when multiple Metabolonote systems are operated.

• After the second line, the line with data on the first column

sample_set	id	SE1

[layer name][tab]id[tab][metadata ID]

• After the second line, the line without data on the first column

	title	Arabidopsis thaliana metabolite analysis

[tab][field name][tab][value]

[layer name] and [field name] are specified based on this definition. The layer name of the field of the line without data on the first column is the same name with that of the line higher than the relevant line.

xml format

The output is XML based on the XML schema described XML tag definition.

mode

You can select the layers to output.

all (default)

The output includes information of all the layers higher than the specified metadata ID and the related metadata, such as MS layer for M, and DS for D.

single

The output includes only the information of the layer specified by metadata ID. The related metadata (MS for M, and DS for D) are not included.

related

The output includes the information of the layer specified by metadata ID, and the related metadata (MS for M, and DS for D).

getDataByMetadataIdWithAM

Action Name	getDataByMetadataIdWithAM
Description	Obtains metadata based on the metadata ID. You can select the data output format from the tab-separated text (txt) format and the XML (xml) format. When the data analysis ID (D) is specified, the metadata for annotation methods (AM) is attached to the output. You can attach the specified metadata (AM*) or metadata of all the AMs (all) included in the sample set.
Parameter
Key	Description	Value	Essential/Not essential	Default value
id	Target Metadata ID	Metadata ID	Essential
output	Specifies the output format	txt or xml	Not essential	txt
amid	Specifies the annotation method metadata	Annotation Method ID(s) or all	Not essential	all
Sample
https://metabolonote.jp/mnapi.php?action=getDataByMetadataIdWithAM&id=SE1_S01_M01_D01&output=txt&amid=all https://metabolonote.jp/mnapi.php?action=getDataByMetadataIdWithAM&id=SE1_S01_M01_D01&output=xml&amid=AM1 https://metabolonote.jp/mnapi.php?action=getDataByMetadataIdWithAM&id=SE1_S01_M01_D01&output=txt

Parameters

id

Same as getDataByMetadataId

output

Same as getDataByMetadataId

amid

This specifies the annotation method IDs (AM) to output. Notice that the information of AM(s) is only attached when the data analysis ID (layer D) is specified to the "id" parameter.

all (default)

All the AM metadata included in the sample set are attached.

AM*

Only the metadata specified by ID (AM*) is attached. You can specify multiple AM IDs by connecting them with comma as shown below.

&amid=AM1
&amid=AM1,AM2

getPropertiesByMetadataId

Action name	getPropertiesByMetadataId
Description	Obtains a set of property names and their values of the metadata based on the metadata ID.
Parameter
Key	Description	Value	Essential/Not essential	Default value
id	Target metadata ID	Metadata ID	Essential
output	Specifies the output format (only JSON format is available at present)	json	Not essential	json
Sample
https://metabolonote.jp/mnapi.php?action=getPropertiesByMetadataId&id=SE1_S01_M01

Parameters

id

Same as getDataByMetadataId

output

json: JSON format (default)

getLastUpdateOfMetadata

Action name	getLastUpdateOfMetadata
Description	Obtaines the last update time of the metadata based on the metadata ID. The return value is in the Unix time (seconds elapsed since January 1st, 1970).
Parameter
Key	Description	Value	Essential/Not essential	Default value
id	Target metadata ID	Metadata ID	Essential
output	Specifies the output format (only JSON format is available now)	json	Not essential	json
Sample
https://metabolonote.jp/mnapi.php?action=getLastUpdateOfMetadata&id=SE1_S01_M01_D01

Parameters

id

Same as getDataByMetadataId

output

json: JSON format (default)

getLastUpdateInMetadataSet

Action name	getLastUpdateInMetadataSet
Description	The term "metadata set" indicates here a set of all metadata belong to the top layer of the metadata format. The "metadata set ID" indicates the ID of the metadata at the top layer. In Metabolonote, the Sample Set ID is the metadata set ID. This API function obtains the latest update time of the metadata set. The return value is in the Unix time (seconds elapsed since January 1st, 1970).
Parameter
Key	Description	Value	Essential/Not essential	Default value
id	Target metadata set ID	Metadata set ID	Essential
output	Specifies output format. (only JSON format is available now)	json	Not essential	json
mode	Scope of evaluation (see below)	single or all	Not essential	single
Sample
https://metabolonote.jp/mnapi.php?action=getLastUpdateInMetadataSet&id=SE3&mode=single https://metabolonote.jp/mnapi.php?action=getLastUpdateInMetadataSet&id=SE3&mode=all

Parameters

id

Specifies the metadata set ID (the ID of the metadata at the top layer of the metadata format). Error message is returned if the other IDs at the lower layer of the metadata format is set.

id:       SE1

output

json: JSON format (default)

mode

single (default):

Returns the last update time of the metadata ID. The same result to getLastUpdateOfMetadata is obtained.

all

Returns the latest update time in all the metadata in the metadata set.

getFixedDataByPropertyName

Action name	getFixedDataByPropertyName
Description	Obtains a list of static values set to the property name.
Parameter
Key	Description	Value	Essential/Not essential	Default value
pname	The target property name	Property name	Essential
output	Specifies the output format. (only JSON format is available now)	json	Not essential	json
Sample
https://metabolonote.jp/mnapi.php?action=getFixedDataByPropertyName&pname=MS_Instrument_Type

Parameters

pname

The target property name. The official property names used in Metabolonote is described here.

output

json: JSON format (default)

getAllPageIds

Action name	getAllPageIds
Description	Obtains all the metadata IDs published from the Metabolonote system.
Parameter
Key	Description	Value	Essential/Not essential	Default value
output	Specifies the output format. (only JSON format is available now)	json	Not essential	json
Sample
https://metabolonote.jp/mnapi.php?action=getAllPageIds

Parameters

output

json: JSON format (default)

getTopPageIds

Action name	getTopPageIds
Description	Obtains a list of metadata IDs that are at the top layer of the metadata format. In the case of Metabolonote, a list of the Sample set IDs (SE*) published is returned.
Parameter
Key	Description	Value	Essential/Not essential	Default value
output	Specifies the output format. (only JSON format is available now)	json	Not essential	json
Sample
https://metabolonote.jp/mnapi.php?action=getTopPageIds

Parameters

output

json: JSON format (default)

getSubPageIdsByMetadataId

Action name	getSubPageIdsByMetadataId
Description	Obtains a list of metadata IDs that are placed at the layer one level lower than the layer of the given metadata ID.
Parameter
Key	Description	Value	Essential/Not essential	Default value
id	The target metadata ID	Metadata ID	Essential
output	Specifies the output format. (only JSON format is available now)	json	Not essential	json
Sample
https://metabolonote.jp/mnapi.php?action=getSubPageIdsByMetadataId&id=SE1_S01

Parameters

id

Same as getDataByMetadataId

output

json: JSON format (default)

getLowerPageIdsByMetadataId

Action name	getLowerPageIdsByMetadataId
Description	Obtains a list of all metadata IDs that are included in the all lower layers than the layer of the given metadata ID.
Parameter
Key	Description	Value	Essential/Not essential	Default value
id	The target metadata ID	Metadata ID	Essential
output	Specifies the output format. (only JSON format is available now)	json	Not essential	json
Sample
https://metabolonote.jp/mnapi.php?action=getLowerPageIdsByMetadataId&id=SE1_S01

Parameters

id

Same as getDataByMetadataId

output

json: JSON format (default)

getSourcePageIdsByReferentPageId

Action name	getSourcePageIdsByReferentPageId
Description	Obtains ID of source metadata that refers the given metadata ID. In Metabolonote, for example, the analytical method IDs (M*) are returned by the given analytical method details (MS*).
Parameter
Key	Description	Value	Essential/Not essential	Default value
id	The referent metadata ID.	Metadata ID	Essential
output	Specifies the output formatl (only JSON format is available now)	json	Not essential	json
Sample
https://metabolonote.jp/mnapi.php?action=getSourcePageIdsByReferentPageId&id=SE1_MS1

Parameters

id

Same as getDataByMetadataId

output

json: JSON format (default)

getOfficialNames

Action name	getOfficialNames
Description	Obtains a list of the official names used in the Metabolonote.
Parameter
Key	Description	Value	Essential/Not essential	Default value
output	Specifies the output format. (only JSON format is available now)	json	Not essential	json
Sample
https://metabolonote.jp/mnapi.php?action=getOfficialNames

Parameters

output

json: JSON format (default)

APIs for Searching

searchPageIdsByProperty

Action name	searchPageIdsByProperty
Description	Obtains a list of metadata IDs one of whose spesified property includes the given value.
Parameter
Key	Description	Value	Essential/Not essential	Default value
pname	The target property name	Property name	Essential
keyword	A string to query	Query string	Essential
output	Specifies the output format (only JSON format is available now)	json	Not essential	json
case	Consideration of case sensitivity	yes or no	Not essential	no
exact	Matching mode.	yes (exact matching) or no (partial matching)	Not essential	no
Sample
http://metabolonote.kazusa.or.jp/mnapi.php?action=searchPageIdsByProperty&pname=SE_Title&keyword=arabidopsis

Parameters

pname

The property name. The exact property name is described here.

keyword

The query string

output

json: JSON format (default)

case

yes: case sensitive

no: case insensitive

exact

yes: exact match

no: partial match

searchPageIdsByProperties

Action name	searchPageIdsByProperties
Description	Obtains an ID list of metadata which include multiple properties of given values.
Parameter
Key	Description	Value	Essential/Not essential	Default value
Property Name	Specifies a target property name as a key and a query string as a value.	Query string	Essential
output	Specifies the output format (only JSON format is available now)	json	Not essential	json
case	Consideration of case sensitivity	yes or no	Not essential	no
exact	Matching mode	yes (exact matching) or no (partial matching)	Not essential	no
mode	Mode of multiple condition search	and (AND searching) or or (OR searching)	Not essential	and
Sample
http://metabolonote.kazusa.or.jp/mnapi.php?action=searchPageIdsByProperties&SE_Title=arabidopsis&MS_Ion_Mode=positive http://metabolonote.kazusa.or.jp/mnapi.php?action=searchPageIdsByProperties&SE_Title=arabidopsis&MS_Ion_Mode=positive&mode=or

Parameters

Property Name

Specifies a target property name as a key and a query string as a value. Multiple key-value pairs can be set.

The property names used in Metabolonote is described here.

ex.)
&SE_Title=Arabidopsis&MS_Ion_Mode=Positive
&[PropertyName]=[Keyword]&[PropweryName]=[Keyword]

output

json: JSON format (default)

case

yes: case sensitive

no: case insensitive

exact

yes: exact matching

no: partial matching

mode

and: AND searching

The metadata that hit to all the given searching conditions (property name - query string pairs) are returned.

or: OR searching

The metadata that hit to one of the given searching conditions (property name - query string pairs) are returned.

APIs Deprecated

The following API functions are deprecated. There are provided only for compatibility to older versions.

getMsInstrumentTypes (deprecated)

This function is specific for the metadata setting of Metabolonote. Use the generarized function getFixedDataByPropertyName instead.

Action name	getMsInstrumentTypes
Description	Obtaines a list of values set to the property 'MS_Instrument_TypeMetabolonote'.
Parameter
Key	Description	Value	Essential/Not essential	Default value
output	Specify the output format. (only JSON format is available)	json	Not Essential	json
Sample
http://metabolonote.kazusa.or.jp/mnapi.php?action=getMsInstrumentTypes

Parameters

output

json: JSON format (default)

getSampleIdsUsingSsId (deprecated)

This function is specific for the metadata setting of Metabolonote. Use the generalized function getSourcePageIdsByReferentPageId instead.

Action name	getSampleIdsUsingSsId
Description	Obtaines Sample IDs that referring given Sample Details ID (SS ID).
Parameter
Key	Description	Value	Essential/Not essential	Default value
ssid	The target Sample Details ID	Sample Details ID	Essential
output	Specifies the output format (only JSON format is available now)	json	Not essential	json
Sample
http://metabolonote.kazusa.or.jp/mnapi.php?action=getSampleIdsUsingSsId&msid=SE1_SS1

Parameters

ssid

Same as getDataByMetadataId

id:        SE1_SS1   <- Use this
Page Name: SE1:/SS1

output

json: JSON format (default)

getMethodIdsUsingMsId (deprecated)

This function is specific for the metadata setting of Metabolonote. Use the generalized function getSourcePageIdsByReferentPageId instead.

Action name	getMethodIdsUsingMsId
Description	Obtaines a list of Analytical Method IDs (M*) that referring the given Analytical Method Details ID (MS*)
Parameter
Key	Description	Value	Essential/Not essential	Default value
msid	The target Analytical Method Details ID	Analytical Method Details ID	Essential
output	Specifies the output format (only JSON format is available now)	json	Not essential	json
Sample
http://metabolonote.kazusa.or.jp/mnapi.php?action=getMethodIdsUsingMsId&msid=SE1_MS1

Parameters

msid

Same as getDataByMetadataId

id:        SE1_MS1   <- Use this
Page name: SE1:/MS1

output

json: JSON format (default)

json: JSON形式

getDataAnalysisIdsUsingDsId (deprecated)

This function is specific for the metadata setting of Metabolonote. Use the generalized function getSourcePageIdsByReferentPageId instead.

Action name	getDataAnalysisIdsUsingDsId
Description	Obtailes a list of Data Analysis IDs (D*) that referring the given Data Analysis Details ID (DS*).
Parameter
Key	Description	Value	Essential/Not essential	Default value
dsid	The Data Analysis Details ID	The Data Analysis Details ID	Essential
output	Specifies the output format (only JSON format is available now)	json	Not Essential	json
Sample
http://metabolonote.kazusa.or.jp/mnapi.php?action=getDataAnalysisIdsUsingDsId&dsid=SE1_DS1

Parameters

dsid

Same as getDataByMetadataId

id:        SE1_DS1   <- Use this
Page Name: SE1:/DS1

output

json: JSON format (default)