Back to top

API for Latent Environment Allocation Global Map

This is a brief specification document for the REST API used in LEA global map.

Resource Group

Search samples

Search samples API
GET/string/{searched_string}/samples{?n_limit}

  • Returns samples relevant to the input searche query.

    • The upper limit of the number of samples is specified by n_limit.
    • Samples are returned in descending order of their relevance within the upper limit.
    • Each sample is returned as an object and has the following values:
      • value: Score of relevance to the search query
      • sample_id: Sample ID

  • Default value of n_limit is 10.

  • searched_string is a mandatory parameter. Returns Bad Request if not specified.

  • If there is no hit in the search result, return an empty array.

Example URI

GET http://snail.nig.ac.jp/leaapi/string/hot spring/samples?n_limit=10
URI Parameters
HideShow
searched_string
string (required) Example: hot spring

search query

n_limit
number (optional) Example: 10

upper limit of the number of samples to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "sample_list": [
    {
      "sample_id": "DRS000009",
      "value": 0.05
    },
    {
      "sample_id": "ERS123456",
      "value": 0.045
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "sample_list": {
      "type": "array"
    }
  },
  "required": [
    "sample_list"
  ]
}

Semantic suggestion

Semantic suggestion API
GET/string/{searched_string}/topics/semantic{?n_topic_limit,n_element_limit}

  • Returns words and microbes “semantically similar” to the input string, that is, words and microbes belonging to the most relevant topic.

    • The upper limit of the number of topics is specified by n_topic_limit.
    • The upper limit of the number of elements of each topic is specified by n_element_limit.
    • Topics and elements are returned in descending order of their relevance within the upper limit.

  • Default value of n_topic_limit is 1.

  • Default value of n_element_limit is 5.

  • searched_string is a mandatory parameter. Returns Bad Request if not specified.

  • If there is no hit in the search result, return an empty array.

Example URI

GET http://snail.nig.ac.jp/leaapi/string/hot spring/topics/semantic?n_topic_limit=10&n_element_limit=10
URI Parameters
HideShow
searched_string
string (required) Example: hot spring

search query

n_topic_limit
number (optional) Example: 10

upper limit of the number of topics to return

n_element_limit
number (optional) Example: 10

upper limit of the number of elements of each topic to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "topic_list": [
    {
      "word": [
        {
          "word": "soil",
          "value": 0.87
        },
        {
          "word": "dog",
          "value": 0.6
        },
        {
          "word": "wood",
          "value": 0.55
        },
        {
          "word": "forest",
          "value": 0.43
        },
        {
          "word": "leaf",
          "value": 0.23
        }
      ],
      "taxonomy": [
        {
          "taxon": "enterococcus",
          "value": 0.95
        },
        {
          "taxon": "streptococcus",
          "value": 0.44
        },
        {
          "taxon": "betabactor",
          "value": 0.39
        },
        {
          "taxon": "proteobacteria",
          "value": 0.2
        },
        {
          "taxon": "actinobacteria",
          "value": 0.02
        }
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "topic_list": {
      "type": "array"
    }
  },
  "required": [
    "topic_list"
  ]
}

Ecological suggestion

Ecological suggestion API
GET/string/{searched_string}/topics/ecological{?n_topic_limit,n_element_limit}

  • Returns words and microbes “ecologically related” to the input string, that is, words and microbes belonging to the topic close to the “semantically similar” topic on the LEA global map.

    • The upper limit of the number of topics is specified by n_topic_limit.
    • The upper limit of the number of elements of each topic is specified by n_element_limit.
    • Topics and elements are returned in descending order of their relevance within the upper limit.

  • Default value of n_topic_limit is 1.

  • Default value of n_element_limit is 5.

  • searched_string is a mandatory parameter. Returns Bad Request if not specified.

  • If there is no hit in the search result, return an empty array.

Example URI

GET http://snail.nig.ac.jp/leaapi/string/hot spring/topics/ecological?n_topic_limit=3&n_element_limit=5
URI Parameters
HideShow
searched_string
string (required) Example: hot spring

search query

n_topic_limit
number (optional) Example: 3

upper limit of the number of topics to return

n_element_limit
number (optional) Example: 5

upper limit of the number of elements of each topic to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "topic_list": [
    {
      "word": [
        {
          "word": "soil",
          "value": 0.43
        },
        {
          "word": "dog",
          "value": 0.22
        },
        {
          "word": "wood",
          "value": 0.11
        },
        {
          "word": "forest",
          "value": 0.06
        },
        {
          "word": "leaf",
          "value": 0.01
        }
      ],
      "taxonomy": [
        {
          "taxon": "enterococcus",
          "value": 0.83
        },
        {
          "taxon": "streptococcus",
          "value": 0.55
        },
        {
          "taxon": "betabactor",
          "value": 0.4
        },
        {
          "taxon": "proteobacteria",
          "value": 0.3
        },
        {
          "taxon": "actinobacteria",
          "value": 0.23
        }
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "topic_list": {
      "type": "array"
    }
  },
  "required": [
    "topic_list"
  ]
}

Sample locations

Sample locations API
GET/sample/location

  • Returns sample coordinates on the LEA global map.

Example URI

GET http://snail.nig.ac.jp/leaapi/sample/location
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "sample_list": [
    {
      "x": 23.4,
      "y": 235.2,
      "color": "\"#9428ff\"",
      "sample_id": "DRS000009"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "sample_list": {
      "type": "array"
    }
  },
  "required": [
    "sample_list"
  ]
}

Sample metadata

Sample metadata API
GET/sample/{sample_id}/metadata

  • Returns metadata of an input sample.

  • sample_id is a mandatory parameter. Returns Bad Request if not specified.

  • If there is no sample_id, return Not Found.

Example URI

GET http://snail.nig.ac.jp/leaapi/sample/DRS000009/metadata
URI Parameters
HideShow
sample_id
string (required) Example: DRS000009
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "metadata": {
    "sample_name": "hot spring sample",
    "sample_url": "http://example.com/SRS123456"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "metadata": {
      "type": "object",
      "properties": {
        "sample_name": {
          "type": "string"
        },
        "sample_url": {
          "type": "string"
        }
      },
      "required": [
        "sample_name",
        "sample_url"
      ]
    }
  },
  "required": [
    "metadata"
  ]
}

Sample topic composition

Sample topic composition API
GET/sample/{sample_id}/topics

  • Returns topic composition of an input sample.

  • sample_id is a mandatory parameter. Returns Bad Request if not specified.

  • If there is no sample_id, return Not Found.

Example URI

GET http://snail.nig.ac.jp/leaapi/sample/DRS000009/topics
URI Parameters
HideShow
sample_id
string (required) Example: DRS000009
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "topic_list": [
    {
      "topic_id": 4,
      "value": 0.34
    },
    {
      "topic_id": 42,
      "value": 0.29
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "topic_list": {
      "type": "array"
    }
  },
  "required": [
    "topic_list"
  ]
}

Sample taxonomic composition

Sample taxonomic composition API
GET/sample/{sample_id}/taxonomies/{taxon_rank}

  • Returns taxonomic composition of an input sample.

  • sample_id and taxon_rank are mandatory parameters. Returns Bad Request if not specified.

  • If there is no sample_id, return Not Found.

  • If invalid taxon_rank is specified, return Bad Request.

Example URI

GET http://snail.nig.ac.jp/leaapi/sample/DRS000009/taxonomies/genus
URI Parameters
HideShow
sample_id
string (required) Example: DRS000009
taxon_rank
string (required) Example: genus
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "taxonomy_list": [
    {
      "taxonomy_name": "firmicutes",
      "value": 0.34
    },
    {
      "taxonomy_name": "proteobacteria",
      "value": 0.22
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "taxonomy_list": {
      "type": "array"
    }
  },
  "required": [
    "taxonomy_list"
  ]
}

Topic locations

Topic locations API
GET/topic/location

  • Returns topic coordinates on the LEA global map.

Example URI

GET http://snail.nig.ac.jp/leaapi/topic/location
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "topic_list": [
    {
      "x": 23.4,
      "y": 235.2,
      "topic_id": 5
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "topic_list": {
      "type": "array"
    }
  },
  "required": [
    "topic_list"
  ]
}

Topic metadata

Topic metadata API
GET/topic/{topic_id}/metadata

  • Returns metadata of an input topic.

  • topic_id is a mandatory parameter. Returns Bad Request if not specified.

  • If there is no topic_id, return Not Found.

Example URI

GET http://snail.nig.ac.jp/leaapi/topic/0/metadata
URI Parameters
HideShow
topic_id
number (required) Example: 0
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "metadata": {
    "Attribution": "No attribution required",
    "ImageURL": "https://pixabay.com/en/background",
    "License": "CC0 Public Domain"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "metadata": {
      "type": "object",
      "properties": {
        "Attribution": {
          "type": "string"
        },
        "ImageURL": {
          "type": "string",
          "description": "blue-floor-ocean-sand-17520/ (string, required)"
        },
        "License": {
          "type": "string"
        }
      },
      "required": [
        "Attribution",
        "License"
      ]
    }
  },
  "required": [
    "metadata"
  ]
}

Topic words composition

Topic words composition API
GET/topic/{topic_id}/words{?n_word_limit}

  • Returns words composition of an input topic.

    • The upper limit of the number of words is specified by n_word_limit.

  • Default value of n_word_limit is 5.

  • topic_id is a mandatory parameter. Returns Bad Request if not specified.

  • If there is no topic_id, return Not Found.

Example URI

GET http://snail.nig.ac.jp/leaapi/topic/4/words?n_word_limit=5
URI Parameters
HideShow
topic_id
number (required) Example: 4
n_word_limit
number (optional) Example: 5

upper limit of the number of words to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "word_list": [
    {
      "word": "dog",
      "value": 0.34
    },
    {
      "word": "foot",
      "value": 0.21
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "word_list": {
      "type": "array"
    }
  },
  "required": [
    "word_list"
  ]
}

Topic taxonomic composition

Topic taxonomic composition API
GET/topic/{topic_id}/taxonomies/{taxon_rank}

  • Returns taxonomic composition of an input topic.

  • topic_id and taxon_rank are mandatory parameters. Returns Bad Request if not specified.

  • If there is no topic_id, return Not Found.

  • If invalid taxon_rank is specified, return Bad Request.

Example URI

GET http://snail.nig.ac.jp/leaapi/topic/4/taxonomies/genus
URI Parameters
HideShow
topic_id
number (required) Example: 4
taxon_rank
string (required) Example: genus
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "taxonomy_list": [
    {
      "taxonomy_name": "firmicutes",
      "value": 0.34
    },
    {
      "taxonomy_name": "proteobacteria",
      "value": 0.25
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "taxonomy_list": {
      "type": "array"
    }
  },
  "required": [
    "taxonomy_list"
  ]
}

Taxonomic color

Taxonomic color API
GET/taxonomy/color

  • Returns colors of each genus (same colors for genera belonging to the same phylum)

Example URI

GET http://snail.nig.ac.jp/leaapi/taxonomy/color
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "taxonomy_list": [
    {
      "color": "#c7869e",
      "taxonomy_name": "Methylobacillus"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "taxonomy_list": {
      "type": "array"
    }
  },
  "required": [
    "taxonomy_list"
  ]
}

Predict new sample

Predict new sample API
POST/new_sample

  • Receives the VITCOMIC2 cluster file (for a single sample, or gzip compressed tar archive for multiple samples) and returns their coordinates.

  • cluster_file are mandatory parameters. Returns Bad Request if not specified.

  • Returns Bad Request if cluster_file is neither application/octet-stream (for a single sample) nor application/x-gzip (for multiple samples).

Example URI

POST http://snail.nig.ac.jp/leaapi/new_sample
Request
HideShow
Headers
Content-Type: application/octet-stream
Request
HideShow
Headers
Content-Type: application/x-gzip
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "new_sample_list": [
    {
      "project_id": "20170420051049db365f9fd4982d274d378c79d35fda30",
      "sample_id": "Kako",
      "x": 149.6,
      "y": 3.9,
      "color": "#fde724"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "new_sample_list": {
      "type": "array"
    }
  },
  "required": [
    "new_sample_list"
  ]
}

Predict new sample by 100 Gibbs sampling chains

Predict new sample 100 Gibbs API
POST/new_sample_sd

  • Receives the VITCOMIC2 cluster file (for a single sample, or gzip compressed tar archive for multiple samples) and returns their topic proportions.

  • Topic proportions are calculated by drawing 100 samples from 100 independent Gibbs sampling chains with different initial settings and by averaging 100 samples. This also provides standard deviations of each topic proportion estimates.

  • The calculation takes a very long long time, so please be patient.

  • cluster_file are mandatory parameters. Returns Bad Request if not specified.

  • Returns Bad Request if cluster_file is neither application/octet-stream (for a single sample) nor application/x-gzip (for multiple samples).

  • For example, if you run with curl: “curl -X POST http://snail.nig.ac.jp/leaapi/new_sample_sd -F ‘cluster_file=@my_samples.tar.gz;type=application/x-gzip’ > result.json”

Example URI

POST http://snail.nig.ac.jp/leaapi/new_sample_sd
Request
HideShow
Headers
Content-Type: application/octet-stream
Request
HideShow
Headers
Content-Type: application/x-gzip
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "new_sample_list": [
    {
      "project_id": "20170420051049db365f9fd4982d274d378c79d35fda30",
      "sample_id": "Kako",
      "topic_list": [
        {
          "topic_id": 0,
          "mean": 0.34,
          "sd": 0.02
        },
        {
          "topic_id": 1,
          "mean": 0.02,
          "sd": 0.00018
        }
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "new_sample_list": {
      "type": "array"
    }
  },
  "required": [
    "new_sample_list"
  ]
}

New sample locations

New sample locations API
GET/newsample/{project_id}/location

  • Returns new sample coordinates on the LEA global map.

Example URI

GET http://snail.nig.ac.jp/leaapi/newsample/20170420051049db365f9fd4982d274d378c79d35fda30/location
URI Parameters
HideShow
project_id
string (required) Example: 20170420051049db365f9fd4982d274d378c79d35fda30
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "new_sample_list": [
    {
      "project_id": "20170420051049db365f9fd4982d274d378c79d35fda30",
      "sample_id": "Kako",
      "x": 149.6,
      "y": 3.9,
      "color": "#fde724"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "new_sample_list": {
      "type": "array"
    }
  },
  "required": [
    "new_sample_list"
  ]
}

New sample topic composition

New sample topic composition API
GET/newsample/{project_id}/{sample_id}/topics

  • Returns topic composition of input project_id and sample_id.

  • If there is no project_id or sample_id, return Not Found.

Example URI

GET http://snail.nig.ac.jp/leaapi/newsample/20170420051049db365f9fd4982d274d378c79d35fda30/Kako/topics
URI Parameters
HideShow
project_id
string (required) Example: 20170420051049db365f9fd4982d274d378c79d35fda30
sample_id
string (required) Example: Kako
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "topic_list": [
    {
      "topic_id": 4,
      "value": 0.34
    },
    {
      "topic_id": 42,
      "value": 0.29
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "topic_list": {
      "type": "array"
    }
  },
  "required": [
    "topic_list"
  ]
}

New sample taxonomic composition

New sample taxonomic composition API
GET/newsample/{project_id}/{sample_id}/taxonomies/{taxon_rank}

  • Returns taxonomic composition of input project_id and sample_id.

  • If there is no project_id or sample_id, return Not Found.

  • If invalid taxon_rank is specified, return Bad Request.

Example URI

GET http://snail.nig.ac.jp/leaapi/newsample/20170420051049db365f9fd4982d274d378c79d35fda30/Kako/taxonomies/genus
URI Parameters
HideShow
project_id
string (required) Example: 20170420051049db365f9fd4982d274d378c79d35fda30
sample_id
string (required) Example: Kako
taxon_rank
string (required) Example: genus
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "taxonomy_list": [
    {
      "taxonomy_name": "firmicutes",
      "value": 0.34
    },
    {
      "taxonomy_name": "proteobacteria",
      "value": 0.22
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "taxonomy_list": {
      "type": "array"
    }
  },
  "required": [
    "taxonomy_list"
  ]
}

Generated by aglio on 15 Oct 2018