• Home
• General Usage
• Term Search
• Ontology Property Search
• Annotator
• Recommender
• Batch
• Ontology Analytics
• Resources
  • Media Types and Hypermedia Links
    • Agent
    • Category
    • Class
    • Group
    • IdentifierRequest
    • Instance
    • Mapping
    • Metric
    • Note
    • Reply
    • ObjectProperty
    • Ontology
    • OntologySubmission
    • Project
    • ProvisionalClass
    • ProvisionalRelation
    • Review
    • Collection
    • Scheme
    • Slice
    • User
• Content Types

EcoPortal API Documentation

General Usage

This API is comprised of a set of resources (Ontologies, Classes, etc) and related endpoints (Search, Annotator, Recommender) that are connected together via links, much like webpages. We recommend that you try browsing the API using a web browser (Chrome and Firefox work very well while IE does not) before you start writing code. For more information, please see the documentation on Media Types and Hypermedia Links or view our sample code , available in Java, Python, Ruby and other languages (please email support@bioontology.org if you would like examples in another language).

Common Parameters

Parameter	Possible Values	Description
apikey	{your api key}	An API Key is required to access any API call. It can be provided in three ways: Using the apikey query string parameter Providing an Authorization header: Authorization: apikey token=your_apikey (replace `your_apikey` with your actual key) When using a web browser to explore the API, if you provide your API Key once using method 1, it will be stored in a cookie for subsequent requests. You can override this by providing a different API Key in a new call.
include	all {comma-separated list of attributes, EX: attr1,attr2}	By default, the API will show a subset of the available attributes for a given media type. This behavior can be overridden by providing include=all to show all attributes or include=attribute1,attribute2 to include a specific list. The API is optimized to return the default values, so overriding this can impact the performance of your request. The include=all option is most useful for testing in the browser. Use it to identify the set of attributes required and use only those by passing them as a comma separated list, e.g. include=prefLabel,cui. The include parameter is currently unsupported on Annotator and Recommender endpoints.
format	json jsonp xml	The API returns JSON as the default content type. This can be overridden by using the format query string parameter. The API also respects Accept header entries, with precedence given to the format parameter.
page	{integer representing the page number}	For calls that are paged, this will indicate which page number you want to retrieve. You can follow hypermedia links for nextPage and prevPage as well.
pagesize	{integer representing the size of the returned page}	For calls that are paged, this will indicate the size of the page you want to retrieve.
include_views	{boolean representing whether or not to include ontology views (default is false)}	For calls that involve ontologies, include_views='true' will include ontology views.
display_context	{true|false} (defaults to true)	Turn off the JSON-LD context serialization. This will reduce the response size significantly for some calls, speeding up transmission and parse time.
display_links	{true|false} (defaults to true)	Turn off the hypermedia link serialization. This will reduce the response size significantly for some calls, speeding up transmission and parse time.
download_format	{csv|rdf} (defaults to user-uploaded file format)	Allows you to specify alternative formats for ontology file downloads for ontology and ontology submission download endpoints. CSV is only available for the most recent submission.

Search, Annotator, Recommender, and Resource Index Endpoints

Several endpoints are available for performing lookups for classes, annotations, and annotated resources. These endpoints are not strictly RESTful, but do return objects with links where relevant.

Term Search

An endpoint for searching terms and their properties is available

• Perform search
• GET POST /search?q={search query}
• example: /search?q=melanoma
• Parameters
  • ontologies={ontology_id1,ontology_id2,ontology_id3}
  • require_exact_match={true|false} // default = false
  • suggest={true|false} // default = false. Will perform a search specifically geared towards type-ahead suggestions.
  • also_search_views={true|false} // Include ontology views in the search. default = false
  • require_definitions={true|false} // default = false
  • also_search_properties={true|false} // default = false
  • also_search_obsolete={true|false} // default = false (exclude obsolete terms)
  • cui={C0018787,C0225807,C0018787} // Allows restricting query by CUIs. default = null (no restriction)
  • semantic_types={T023,T185,T061} // Allows restricting query by Semantic Types (TUI). default = null (no restriction)
  • include={prefLabel, synonym, definition, notation, cui, semanticType} // default = (see Common Parameters section)
  • page={integer representing the page number} // default = 1
  • pagesize={integer representing the size of the returned page} // default = 50

Subtree Search

The same endpoint also allows limiting a search to a given subtree/branch. The root of the subtree is defined using a combination of parameters "ontology" and "subtree_root_id". Both are required when performing a subtree search.

• Perform a subtree search
• example: /search?q=melanoma&ontology=NCIT&subtree_root_id=http%3a%2f%2fncicb.nci.nih.gov%2fxml%2fowl%2fEVS%2fThesaurus.owl%23C3224
• Parameters
  • ontology={ontology_id}
  • subtree_root_id={a URI encoded class id of the root node of the subtree}

Roots Only Search

The same endpoint allows limiting a search to root classes only.

• Perform a roots-only search
• example: /search?q=melanoma&ontology=NCIT,GO&roots_only=true
• Parameters
  • roots_only={true|false}

Ontology Property Search

An endpoint for searching ontology properties by their labels and IDs (URIs)

• Perform search
• GET POST /property_search?q={search query}
• example: /property_search?q=has dimension
• Parameters
  • ontologies={ontology_id1,ontology_id2,ontology_id3}
  • require_exact_match={true|false} // Restricts results only to the exact matches of the query by the property id, label, or the generated label (a label, auto-generated from the ID). default = false
  • also_search_views={true|false} // Include ontology views in the search. default = false
  • require_definitions={true|false} // Filter results only to those that include definitions. default = false
  • include={label, labelGenerated, definition, parents} // default = All of the properties in this example
  • ontology_types={ONTOLOGY,VALUE_SET_COLLECTION} // default = all ontology types are returned
  • property_types={object,annotation,datatype} // Restricts results to specific property types (object, annotation, datatype). default = all property types are returned
  • page={integer representing the page number} // default = 1
  • pagesize={integer representing the size of the returned page} // default = 50

Annotator

The Annotator endpoint will examine text input and return relevant classes.

• Annotate text
• GET POST /annotator?text={input text}
• example: /annotator?text=Melanoma+is+a+malignant+tumor+of+melanocytes+which+are+found+predominantly+in+skin+but+also+in+the+bowel+and+the+eye.
• Parameters
  • Filtering & query behavior
    • ontologies={ontology_id1,ontology_id2..,ontology_idN}
    • semantic_types={semType1,semType2..,semTypeN}
    • expand_semantic_types_hierarchy={true|false} // default = false. true means to use the semantic types passed in the "semantic_types" parameter as well as all their immediate children. false means to use ONLY the semantic types passed in the "semantic_types" parameter.
    • expand_class_hierarchy={true|false} // default = false. used only in conjunction with "class_hierarchy_max_level" parameter; determines whether or not to include ancestors of the given class when performing an annotation.
    • class_hierarchy_max_level={0..N} // default = 0. the depth of the hierarchy to use when performing an annotation.
    • expand_mappings={true|false} // default = false. true means that the following manual mappings will be used in annotation: UMLS, REST, CUI, OBOXREF.
    • stop_words={word1,word2..,wordN} (case insensitive)
    • minimum_match_length={0..N}
    • exclude_numbers={true|false} // default = false
    • whole_word_only={true|false} // default = true
    • exclude_synonyms={true|false} // default = false
    • longest_only={true|false} // default = false. true means that only the longest match for a given phrase will be returned.
• Default stop words
  • The following stop words are used by default:
    • I, a, above, after, against, all, alone, always, am, amount, an, and, any, are, around, as, at, back, be, before, behind, below, between, bill, both, bottom, by, call, can, co, con, de, detail, do, done, down, due, during, each, eg, eight, eleven, empty, ever, every, few, fill, find, fire, first, five, for, former, four, from, front, full, further, get, give, go, had, has, hasnt, he, her, hers, him, his, i, ie, if, in, into, is, it, last, less, ltd, many, may, me, mill, mine, more, most, mostly, must, my, name, next, nine, no, none, nor, not, nothing, now, of, off, often, on, once, one, only, or, other, others, out, over, part, per, put, re, same, see, serious, several, she, show, side, since, six, so, some, sometimes, still, take, ten, the, then, third, this, thick, thin, three, through, to, together, top, toward, towards, twelve, two, un, under, until, up, upon, us, very, via, was, we, well, when, while, who, whole, will, with, within, without, you, yourself, yourselves

Recommender

The Recommender endpoint receives a text or a list of keywords and suggests appropriate ontologies for them.

• Recommend
• GET POST /recommender?input={input text or keywords}
• example: suggest ontologies for the text "Melanoma is a malignant tumor of melanocytes which are found predominantly in skin but also in the bowel and the eye": /recommender?input=Melanoma%20is%20a%20malignant%20tumor%20of%20melanocytes%20which%20are%20found%20predominantly%20in%20skin%20but%20also%20in%20the%20bowel%20and%20the%20eye
• Parameters
  • input_type={1|2} // default = 1. 1 means that the input type is text. 2 means that the input type is a list of comma separated keywords.
  • output_type={1|2} // default = 1. 1 means that the output will be a ranked list of individual ontologies. 2 means that the output will be a ranked list of ontology sets.
  • max_elements_set={2|3|4} // default = 3. Maximum number of ontologies per set (only for output_type = 2).
  • wc={value in the range [0,1]} // default = 0.55. Weight assigned to the ontology coverage criterion.
  • wa={value in the range [0,1]} // default = 0.15. Weight assigned to the ontology acceptance criterion.
  • wd={value in the range [0,1]} // default = 0.15. Weight assigned to the ontology detail criterion.
  • ws={value in the range [0,1]} // default = 0.15. Weight assigned to the ontology specialization criterion.
  • ontologies={ontology_id1, ontology_id2, …, ontology_idN} // default = (empty) (all BioPortal ontologies will be evaluated).
• Additional examples
  • Suggest ontologies for the keywords "leukocyte, phagocyte, motile cell, metabolising cell, dendritic cell, pipette":
  /recommender?input=leukocyte,phagocyte,motile%20cell,metabolising%20cell,dendritic%20cell,%20pipette&input_type=2
  • Suggest ontologies for the keywords "leukocyte, phagocyte, motile cell, metabolising cell, dendritic cell, pipette", limited to the ontologies UBERON, CL, NCIT and EFO:
  /recommender?input=leukocyte,phagocyte,motile%20cell,metabolising%20cell,dendritic%20cell,%20pipette&input_type=2&ontologies=UBERON,CL,NCIT,EFO
  • Suggest ontology sets for the keywords "leukocyte, phagocyte, motile cell, metabolising cell, dendritic cell, pipette":
  /recommender?input=leukocyte,phagocyte,motile%20cell,metabolising%20cell,dendritic%20cell,%20pipette&input_type=2&output_type=2
  • Suggest ontologies for the text "Melanoma is a malignant tumor of melanocytes which are found predominantly in skin but also in the bowel and the eye", limiting the evaluation to ontology coverage (the weights for the other criteria -acceptance, detail and specialization- will be set to 0):
  /recommender?input=Melanoma%20is%20a%20malignant%20tumor%20of%20melanocytes%20which%20are%20found%20predominantly%20in%20skin%20but%20also%20in%20the%20bowel%20and%20the%20eye&wa=0&wd=0&ws=0

Batch Endpoints

In order to reduce the number of HTTP requests required to obtain information about resources, we are exploring the use of batch endpoints that will use one request/response cycle for multiple resources. Currently, only classes are supported.

POST /batch

The batch service takes input in the BODY of a POST request. The input should be a JSON document with the following structure:

{
    "http://www.w3.org/2002/07/owl#Class": {
        "collection": [
            {
                "class": "http://example.org/ontology1/class1",
                "ontology": "http://example.org/ontology1"
            },
            {
                "class": "http://example.org/ontology2/class1",
                "ontology": "http://example.org/ontology2"
            },
            {
                "class": "http://example.org/ontologyN/classN",
                "ontology": "http://example.org/ontologyN"
            }
        ],
        "display": "prefLabel,synonym,semanticTypes"
    }
}

Example:

{
    "http://www.w3.org/2002/07/owl#Class": {
        "collection": [
            {
                "class": "http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Ontology_Development_and_Management",
                "ontology": "http://data.bioontology.org/ontologies/BRO"
            },
            {
              "class": "http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Modular_Component",
                "ontology": "http://data.bioontology.org/ontologies/BRO"
            },
            {
              "class": "http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Stimulator",
                "ontology": "http://data.bioontology.org/ontologies/BRO"
            }
        ],
        "display": "prefLabel,synonym,semanticTypes"
    }
}

Ontology Analytics

An endpoint for retrieving ontology visitor stats provided by Google Analytics.

Ontology Analytics by Month/Year

Allows to retrieve analytics for all ontologies for a specific month/year combination

• Get ALL analytics data
• GET /analytics
• example: /analytics
• Get analytics data for a given month/year
• GET /analytics?month={month number}&year={year}
• example: /analytics?month=4&year=2014
• Parameters
  • month={1-12}
  • year={2013-...}

Single Ontology Analytics

Allows to retrieve ALL analytics data for a single ontology

• Get analytics data for a given ontology
• GET /ontologies/{acronym}/analytics
• example: /ontologies/NCIT/analytics

Resource Endpoints

Endpoints for RESTful resources can be found below, specifically in the list of Media Types. Using the provided hypermedia links, you can navigate from resource to resource. Each Media Type has a corresponding collection URL (when available), a list of HTTP verbs that can be used to operate on the resources, a description of the resource (including available attributes), and a list of hypermedia links that can be found on each resource.

Media Types and Hypermedia Links

Documentation

The documentation below describes the media types that available in the API and the hypermedia links that connect them. Media types describe the types of resources available, including the HTTP verbs that may be used with them and the attributes that each resource contains.

Hypermedia Links

This programming interface comprises HTTP commands that return objects that themselves contain links to other locations in the form of a URL. In addition to the actual return values, the returned objects contain a set of links to related information. You can access these links using HTTP commands, typically GET. Thus, it is possible to traverse BioPortal's information for an ontology, including classes, notes, and reviews, by starting from the list of ontologies and traversing the available links - either programmatically or in a browser. The different resources are described below, including information about their available attributes, links, and the HTTP verbs that can be used to interact with them.

HTTP Verbs

The API uses different verbs to support processing of resources. This includes things like creating or deleting individual resources or something more specific searching or annotating. Typically, the verbs will be used in conjunciton with the URL that represents the id for a given resource. Here is how we interpret the verbs:

• GET Used to retreive a resource or collection of resources.
• POST Used to create a resource when the server determines the resource's id.
• PUT Used to create a resource when a client determines the resource's id.
• PATCH Used to modify an existing resource. The attributes in a PATCH request will replace existing attributes.
• DELETE Used to delete an existing resource.

Available Media Types

1. http://xmlns.com/foaf/0.1/Agent
2. http://data.bioontology.org/metadata/Category
3. http://www.w3.org/2002/07/owl#Class
4. http://data.bioontology.org/metadata/Group
5. http://data.bioontology.org/metadata/IdentifierRequest
6. http://www.w3.org/2002/07/owl#NamedIndividual
7. http://data.bioontology.org/metadata/Mapping
8. http://data.bioontology.org/metadata/Metrics
9. http://data.bioontology.org/metadata/Note
10. http://data.bioontology.org/metadata/Reply
11. http://www.w3.org/2002/07/owl#ObjectProperty
12. http://data.bioontology.org/metadata/Ontology
13. http://data.bioontology.org/metadata/OntologySubmission
14. http://data.bioontology.org/metadata/Project
15. http://data.bioontology.org/metadata/ProvisionalClass
16. http://data.bioontology.org/metadata/ProvisionalRelation
17. http://data.bioontology.org/metadata/Review
18. http://www.w3.org/2004/02/skos/core#Collection
19. http://www.w3.org/2004/02/skos/core#ConceptScheme
20. http://data.bioontology.org/metadata/Slice
21. http://data.bioontology.org/metadata/User

http://xmlns.com/foaf/0.1/Agent

http://data.bioontology.org/metadata/Category

http://www.w3.org/2002/07/owl#Class

http://data.bioontology.org/metadata/Group

http://data.bioontology.org/metadata/IdentifierRequest

http://www.w3.org/2002/07/owl#NamedIndividual

http://data.bioontology.org/metadata/Mapping

http://data.bioontology.org/metadata/Metrics

http://data.bioontology.org/metadata/Note

http://data.bioontology.org/metadata/Reply

http://www.w3.org/2002/07/owl#ObjectProperty

http://data.bioontology.org/metadata/Ontology

http://data.bioontology.org/metadata/OntologySubmission

http://data.bioontology.org/metadata/Project

http://data.bioontology.org/metadata/ProvisionalClass

http://data.bioontology.org/metadata/ProvisionalRelation

http://data.bioontology.org/metadata/Review

http://www.w3.org/2004/02/skos/core#Collection

http://www.w3.org/2004/02/skos/core#ConceptScheme

http://data.bioontology.org/metadata/Slice

http://data.bioontology.org/metadata/User

Content Types

The API returns JSON as the default content type. This can be overridden by using the format query string parameter with the value json, jsonp, or xml. The API also respects Accept header entries (EX: application/json, application/xml), with precedence given to the format parameter.

JSON

The default content type is JSON, specifically a variant called JSON-LD, or JSON Linked Data. You can treat this variant like normal JSON. All JSON parsers will be able to parse the output normally. The benefit of JSON-LD is that it enables hypermedia links, and you will find these links exposed as URLs in attributes labeled @id, which correspond to the id of the parent resource, or in an array called links, which contains a hash of link types with corresponding URLs.

Here is a sample output of the JSON response format:

{
    "administeredBy": [
        "http://data.bioontology.org/user/nevada"
    ],
    "acronym": "ABA-API-TST",
    "name": "ABA Adult Mouse Brain",
    "@id": "http://data.bioontology.org/ontology/ABA-API-TST",
    "@type": "http://data.bioontology.org/metadata/Ontology",
    "links": {
        "metrics": "http://data.bioontology.org/ontologies/ABA-API-TST/metrics",
        "submissions": "http://data.bioontology.org/ontologies/ABA-API-TST/submissions",
        "classes": "http://data.bioontology.org/ontologies/ABA-API-TST/classes",
        "roots": "http://data.bioontology.org/ontologies/ABA-API-TST/classes/roots",
        "reviews": "http://data.bioontology.org/ontologies/ABA-API-TST/reviews"
    },
    "@context": {
        "@vocab": "http://data.bioontology.org/metadata/",
        "acronym": "http://omv.ontoware.org/2005/05/ontology#acronym",
        "name": "http://omv.ontoware.org/2005/05/ontology#name",
        "administeredBy": {
            "@id": "http://data.bioontology.org/metadata/User",
            "@type": "@id"
        }
    }
}

• Line 7 shows the id for the resource. Doing an HTTP GET on the id will retreive the resource.
• Line 8 shows the media type (see below).
• Line 9 starts the links hash.
• Line 16 is the resource's context, which can be used to determine the type for lists of ids. For example, line 2 lists the ids for users who administer the ontology, which can be determined by looking for the administeredBy attribute in the @context hash.
• If you are interested in the predicate URI values used in the resource, these can be deterined by looking up the attribute in the @context hash or by appending the value of @vocab (line 17) to an attribute name in cases where the attribute isn't listed specifically in the @context.

XML

XML is also available as an alternative content type.

Here is sample output for the XML format:

<ontology>
  <administeredByCollection>
    <administeredBy>http://data.bioontology.org/user/nevada</administeredBy>
  </administeredByCollection>
  <acronym>ABA-API-TST</acronym>
  <name>ABA Adult Mouse Brain</name>
  <id>http://data.bioontology.org/ontology/ABA-API-TST</id>
  <links>
    <self href="http://data.bioontology.org/ontology/ABA-API-TST" rel="http://data.bioontology.org/metadata/Ontology"/>
    <metrics href="/ontologies/ABA-API-TST/metrics"/>
    <submissions href="/ontologies/ABA-API-TST/submissions" rel="http://data.bioontology.org/metadata/OntologySubmission"/>
    <classes href="/ontologies/ABA-API-TST/classes" rel="http://www.w3.org/2002/07/owl#Class"/>
    <roots href="/ontologies/ABA-API-TST/classes/roots" rel="http://www.w3.org/2002/07/owl#Class"/>
    <reviews href="/ontologies/ABA-API-TST/reviews" rel="http://data.bioontology.org/metadata/Review"/>
  </links>
</ontology>

• Line 8 starts the links section
• Lines 9-14 list links by type. The href attribute contains the link location and the rel attribute defines the type of resource that will be found at that location.
• Elements outside of the links can also contain href and rel attributes (coming soon...)