Help:Use Data From External System

From Metabolonote
jump-to-nav Jump to: navigation, search
< Help Top


 En.gif English | Ja.gif 日本語  


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.


Contents

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&key1=value1&key2=value2


(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)
Personal tools
View and Edit Metadata
Variants
Views
Actions