BioPortal Mappings Service

From NCBO Wiki
Jump to: navigation, search

The Mapping Services provide access to term mappings for ontologies stored in BioPortal.

Contents

Related Mapping Documents

Service Signatures

The prefix for all production service URLs is http://rest.bioontology.org/bioportal

  • Note: All parameters must be URL-encoded.
  • Note: All NCBO REST Web services will be required to contain the parameter "apikey=YourApiKey" starting June 2011. The parameter will be added to all Web service calls for the April 27, 2011 release but will not be required until June 2011. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.
  • Note for Application Developers: Application developers will also need to include the apikey parameter on all NCBO Web service calls. This allows us to track usage of our system at the level of an application. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

Common Parameters

The following parameters can be used on any mapping service that returns a list of results:

  • pagesize={page size} - limits how many results to return per call. Default: 5000. Max: 50,000.
  • pagenum={page number} - which page of results to return. Default: 1.
  • submittedby={BioPortal user id} - filters by given user id. Multiple ids can be passed as a comma-separated list.
  • type={automatic|manual} - filters by the mapping type.
  • startdate={ISO 8601 combined date/time. EX: 2010-10-24T18:00Z.} - filter by date range. If provided by itself, BioPortal assumes the range should end with the current date and time.
  • enddate={ISO 8601 combined date/time. EX: 2010-10-24T18:00Z.} - filter by date range. Optional, can be used with startdate to limit results to a particular range.
  • relationships={URI identifiers for relationship types} - filter by relationship type(s). Multiple URIs can be provided as a comma-separated list.
  • sources={mapping source} - filter by mapping source.

Get a single mapping

Get a list of mappings filtered by parameters

  • Description: Get a list of mappings based on provided parameters.
  • Signature: ./mappings/?apikey={YourAPIKey}
  • Optional Parameters: See above.

Get a list of mappings for a term

Get a list of mappings between two terms

Get a list of mappings for an ontology

Get a list of mappings between two ontologies

Create a new mapping

  • Description: Create a mapping.
  • HTTP method: POST
  • Signature: ./virtual/mappings/concepts?apikey={YourAPIKey}
    • NOTE: The "apikey" parameter is part of the signature and MUST be first in the list of parameters.
  • Example: http://rest.bioontology.org/bioportal/virtual/mappings/concepts?submittedby=38128&type=manual&source=http%3A%2F%2Fsig.uw.edu%2Ffma%23Ciliated&target=http%3A%2F%2Fncicb.nci.nih.gov%2Fxml%2Fowl%2FEVS%2FThesaurus.owl%23Gallbladder_Disorder&sourceontology=1053&targetontology=1032&relation=http://test.relation.com&apikey=YourAPIKey
  • Required Parameters
    • source={valid full term id/URI from the source ontology}. Must be URL-encoded. A comma-separated list can be provided for many-to-many mappings.
    • target={valid full term id/URI from the target ontology}. Must be URL-encoded. A comma-separated list can be provided for many-to-many mappings.
    • sourceontology={source ontology id}. This is the ontology's virtual id (generally a four-digit integer).
    • targetontology={target ontology id}. This is the ontology's virtual id (generally a four-digit integer).
    • type={automatic|manual}. Was this mapping generated by an automated process or is it human-created or human-verified?
    • relation={valid URI representing the relation}. This URI should represent the relationship between the source and target. For example, http://www.w3.org/2004/02/skos/core#closeMatch
    • submittedby={valid BioPortal user id}.
  • Optional Parameters:
    • unidirectional={true}. By default, BioPortal will generate two mappings for create request as we assume that they are bidirectional. This behavior can be overridden with this parameter, which will cause BioPortal to only generate a single, unidirectional mapping.
    • comment={comment about the mapping}
    • createdinsourceontologyversion={ontology version id}. Tracks which version the mapping was created against. If this is not provided the most recent version number will be used.
    • createdintargetontologyversion={ontology version id}. Tracks which version the mapping was created against. If this is not provided the most recent version number will be used.
    • The following is information about the source of the mapping.
      • mappingsource={application|organization}. Where the mapping originated from.
      • mappingsourcename={name of the mapping source}
      • mappingsourcecontactinfo={contact info}. Some form of contact info to reach the mapping source. Generally a website, email address, or phone number.
      • mappingsourcesite={valid URL for the website of the mapping source}.
      • mappingsourcealgorithm={description of algorithm}. This provides a description for the algorithm used to generate the mapping, if any.

Update a Mapping

  • Description: Update a mapping with given id.
  • HTTP method: PUT
  • Signature: ./virtual/mappings/concepts?mappingid={mapping_id}&apikey={YourAPIKey}
  • Example: http://rest.bioontology.org/bioportal/virtual/mappings/concepts?submittedby=38128&type=manual&source=http%3A%2F%2Fsig.uw.edu%2Ffma%23Ciliated&target=http%3A%2F%2Fncicb.nci.nih.gov%2Fxml%2Fowl%2FEVS%2FThesaurus.owl%23Gallbladder_Disorder&sourceontology=1053&targetontology=1032&apikey=YourAPIKey
  • Optional Parameters
    • source={valid term id from the source ontology}. Must be URL-encoded. A comma-separated list can be provided for many-to-many mappings.
    • target={valid term id from the target ontology}. Must be URL-encoded. A comma-separated list can be provided for many-to-many mappings.
    • sourceontology={source ontology id}. This is the ontology's virtual id (generally a four-digit integer).
    • targetontology={target ontology id}. This is the ontology's virtual id (generally a four-digit integer).
    • type={automatic|manual}. Was this mapping generated by an automated process or is it human-created or human-verified?
    • relation={valid URI representing the relation}. This URI should represent the relationship between the source and target. For example, http://www.w3.org/2004/02/skos/core#closeMatch
    • submittedby={valid BioPortal user id}.
    • comment={comment about the mapping}
    • createdinsourceontologyversion={ontology version id}. Tracks which version the mapping was created against. If this is not provided the most recent version number will be used.
    • createdintargetontologyversion={ontology version id}. Tracks which version the mapping was created against. If this is not provided the most recent version number will be used.
    • The following is information about the source of the mapping.
      • mappingsource={application|organization}. Where the mapping originated from.
      • mappingsourcename={name of the mapping source}
      • mappingsourcecontactinfo={contact info}. Some form of contact info to reach the mapping source. Generally a website, email address, or phone number.
      • mappingsourcesite={valid URL for the website of the mapping source}.
      • mappingsourcealgorithm={description of algorithm}. This provides a description for the algorithm used to generate the mapping, if any.

Delete a Mapping

  • Description: Delete a mapping with given id.
  • HTTP method: DELETE
  • Signature: ./virtual/mappings/concepts?mappingid={mapping id}&apikey={YourAPIKey}

Mapping Statistics

Get Recent Mappings

Get Number of Mappings To/From Given Ontology

Get Number of Mappings to Terms in Given Ontology

Get Number of Mappings by Users for a Given Ontology

Planned Features

The following features are planned for future implementations.

Web Service

  • Get a set of mappings in a particular mapping set
  • Get a set of mappings based on status (archived = "yes/no")
  • Get a set of notes associated with a given mapping id (Notes service)
  • Upload a set of mappings using CSV or RDF (with validation that concepts exist)
    • Return a set of mappings that were invalid
  • Delete a set of mappings

BioPortal Web Interface

  • Thumbs Up/Thumbs Down voting on mapping validity
  • Create structured notes on mappings
  • Batch import process
Retrieved from "http://www.bioontology.org/wiki/index.php?title=BioPortal_Mappings_Service&oldid=12580"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox