Jump to:

MorphoSource API

The MorphoSource public API supports HTTP GET search requests for published resources. Five types of resources are currently available via the API:

API Resources
Specimens
Media
Taxonomy
Projects
Facilities


The API is a RESTful web service that delivers data as JSON documents. All GET requests must be URL-encoded.

Using the API

All API functions are accessed using URLs in the form
http://www.morphosource.org/api/v1/[command]/[resource type]?[url-encoded parameter list]
where [command] is an API function and [resource type] is one of the following: specimens, media, taxonomy, projects, facilities. [url-encoded parameter list] is an HTTP query string containing command options.
The API presently includes a single command, find, that performs full-text and field-qualified searches on the MorphoSource repository and returns comprehensive resource data.

Locating and retrieving resources

The API Find command is a general purpose tool for locating and retriving a variety of resources from the MorphoSource repository. The search syntax supports both full text and field-qualifiedsearch, wildcards and boolean combinations, allowing queries to be as broad or specific as needed. Results may be ordered by any field present in the response.
The find command takes the following parameters:
OptionDescription
q The query
sort A semicolon delimited list of fields to order the results on. For example: project.name;specimen.specimen_id
start The index of the resource at which to begin returning results. Default is zero (the first resource in the result set)
limit Maximum number of records to return. Must be between 1 and 100. Default is 100
naming Format to use for field names. When set to morphosource Morphosource field names are used. When set to darwincore DarwinCore field names are used whenever possible. If omitted Morphosource field names are used by default.
For example, to find all specimens where the word "molar" is used the API URL is:
http://www.morphosource.org/api/v1/find/specimens?q=molar
This will return the first 100 results. To find the second set of 100 use the start parameter:
http://www.morphosource.org/api/v1/find/specimens?q=molar&start=100
You can page through the result set 100 records at a time by incrementing the start parameter.

The API response

The API Find command will return a JSON object similar to this one:
{
  "status":"ok",
  "q":"taxonomy_names.ht_order:primates",
  "totalResults":1235,
  "returnedResults":25,
  "start":0,
  "results":[
    {
      "institution.name":"Duke University, Evolutionary Anthropology",
      "project.name":"Allen Primate Skull Collection",
      "project.project_id":"77",
      "specimen.absolute_age":"",
      "specimen.body_mass":"",
      "specimen.body_mass_bibref_id":"",
      "specimen.body_mass_comments":"",
      "specimen.catalog_number":"0179",
      "specimen.collected_on":"",
      "specimen.collection_code":"",
      "specimen.collector":"",
      "specimen.created_on":"April 24 2013 at 15:37:02",
      "specimen.description":"",
      "specimen.institution_code":"BAA",
      "specimen.institution_id":"7",
      "specimen.last_modified_on":"October 24 2013 at 14:40:10",
      "specimen.locality_absolute_age":"",
      "specimen.locality_absolute_age_bibref_id":"",
      "specimen.locality_coordinates":"",
      "specimen.locality_datum_zone":"",
      "specimen.locality_description":"DUPC",
      "specimen.locality_easting_coordinate":"",
      "specimen.locality_northing_coordinate":"",
      "specimen.locality_relative_age":"",
      "specimen.locality_relative_age_bibref_id":"",
      "specimen.notes":"",
      "specimen.occurrence_id":"",
      "specimen.reference_source":"Vouchered",
      "specimen.relative_age":"adult",
      "specimen.type":"Yes",
      "specimen.sex":"Female",
      "specimen.specimen_id":"17",
      "specimen.url":"",
      "specimen.uuid":"",
      "taxonomy_name":[
        {
          "taxon_id":"24",
          "names":[
            {
              "ht_kingdom":"Animalia",
              "ht_phylum":"Chordata",
              "ht_class":"Mammalia",
              "ht_subclass":"",
              "ht_superorder":"",
              "ht_order":"Primates",
              "ht_suborder":"Strepsirrhini",
              "ht_superfamily":"",
              "ht_family":"Lorisidae",
              "ht_subfamily":"Lorisinae",
              "genus":"Nyticebus",
              "ht_supraspecific_clade":"Lorisidae",
              "species":"coucang",
              "subspecies":"",
              "variety":"",
              "author":"",
              "year":"0",
              "notes":"",
              "created_on":null,
              "last_modified_on":null
            }
          ]
        }
      ],
      "user.email":"kari.allen@wustl.edu"
    },
    ... [ and 185 more ] ...
  ]
}
If the request was successful the status property will be set to ok, otherwise it will be set to err. When an error occurs the message property will include a description of the error. The totalResults property will indicate the total number of resources found, while the returnedResults property contains the number of resources returned in the current request.
The heart of the response is the results property, which contains a list of JSON objects representing each returned resource. The properties of the resource object are resource fields in the form [resource type].[field name]. Most resources will contain fields from related resources in addition to their own fields. For example, specimens in a response also include fields from the project (ex. project.name) and institution (ex. institution.name) they belong to.

Advanced queries

You may restrict your query to any fields contained in the response by prefacing your search text with the field name and a colon. For example to restrict the "molar" query to the specimen element field use
http://www.morphosource.org/api/v1/find/specimens?q=specimen.element:molar
If your search text includes spaces be sure to enclose the text in quotes, otherwise the field qualification will only apply to the text before the first space:
http://www.morphosource.org/api/v1/find/specimens?q=specimen.element:"m2 molar"
(note that the query must be URL encoded – encoding is not applied here for readability)
You may use the "AND" and "OR" keywords to combine several searches into a single result set. To search for all records where either the specimen taxonomy order or specimen notes contains the text "primate":
http://www.morphosource.org/api/v1/find/specimens?q=specimen.notes:primate OR taxonomy_names:ht_order:primate
(again, note that this query must be URL encoded) Using "AND" would return only resources that have primate in both fields.
The wildcard character "*" may be used to match resources having content beginning with a text fragment. For example:
http://www.morphosource.org/api/v1/find/specimens?q=specimen.notes:prim*
Wildcards may be used only at the end of a text fragment. To find all records of a given resource type query on the wildcard character itself. To find, all projects in MorphoSource, for example:
http://www.morphosource.org/api/v1/find/projects?q=*

Sorting

Results may be sorted by any field present in the response, using the field name and the sort option. To sort by specimen element:
http://www.morphosource.org/api/v1/find/specimens?q=molar&sort=specimen.element
Separate field names with semicolons to sort on more than one field:
http://www.morphosource.org/api/v1/find/specimens?q=molar&sort=specimen.element,taxonomy_names.ht_order

Field Names

Results may be returned in JSON using either internal MorphoSource field names or DarwinCore terms. To set the naming convention use the naming option:
http://www.morphosource.org/api/v1/find/specimens?q=molar&naming=darwincore
The codes "morphosource" and "darwincore" will set the API format. If omitted, the API will default to MorphoSource field names.

Data Dictionary

MorphoSource Field Field Description DarwinCore Field
Specimen
absolute_age Absolute age of the specimen earliestEonOrLowestEonothem
body_mass Specimen body mass measurement
body_mass_bibref_id A unique identifier for a bibliographic reference to the body mass of the specimen dcterms:references
body_mass_comments Additional notes regarding the body mass of the specimen measurement
catalog_number Unique alphanumeric string identifying a specimen within a repository and subcollection catalogNumber
collected_on Collection date for specimen eventDate
collection_code Collection code modifier, typically designates a sub-collection within a repository. Not a universal element because not all repositories have sub-collections. However, this field is critical when applicable to avoid confusing specimens from different sub-collections. Please make sure you do not incorrectly omit a collection code fromt the specimen identifier collectionCode
collector Specimen Collector recordedBy
created_on Date of this record's creation N/A
description General description of specimen physical content occurrenceRemarks
institution_code Institution code prefix, mandatory component typically equivalent to repository institution’s acronym in full specimen identifier institutionCode
institution_id Morphosource identifier of the associated institution which owns the physical specimen institutionID
last_modified_on The date/time of the last changes made to the specimen record dcterms:modified
locality_absolute_age Absolute age of locality in years earliestEonOrLowestEonothem
locality_absolute_age_bibref_id A unique identifier for a bibliographic reference to the absolute age of the locality dcterms:references
locality_coordinates Type of geographic reference (e.g. point or Latitude/Longitude) verbatimCoordinates
locality_datum_zone Type of geographic datum type. If datum is UTM the zone is provided. verbatimCoordinateSystem
locality_description General description/name of the locality locality
locality_easting_coordinate Geographic coordinate, given in meters from UTM zone or longitude if system is WGS 84 verbatimLongitude
locality_northing_coordinate Geographic coordinate, given in meters from UTM zone or longitude if system is WGS 84 verbatimLatitude
locality_relative_age Relative age of the locality in geochronologic units lithostratigraphicTerms
locality_relative_age_bibref_id A unique identifier for a bibliographic reference to the relative age of the locality dcterms:references
notes General notes pertaining to the specimen occurrenceRemarks
occurrence_id Unique Institutional identifier for the specimen
project_id MorphoSource identifier for the assocaited project
reference_source Indicates if this specimen was acessioned as part of a collection. "Vouchered" if true, "Unvouchered" if false dynamicProperties
relative_age Relative age of the specimen in geochronologic units lithostratigraphicTerms
sex The sex of the specimen sex
specimen_id MorphoSource identifier for specimen occurrenceID
taxon_id MorphoSource identifier for associated taxonomy associatedTaxa
type Holotype? (yes/no)
url A URL to the specimen's record in the owning institutions' repository or DOI identifier for the record dcterms:references
uuid iDigBio UUID dcterms:references
Facility
address1 Facility Address Line 1 institutionID
address2 Address Line 2 institutionID
city Facility City institutionID
contact Email address for facility contact institutionID
country Facility Country institutionID
created_on Date of creation for facility record institutionID
description Facility Description institutionID
facility_id MorphoSource identifer for the facility institutionID
institution Facility parent institution institutionID
last_modified_on Date the facility record was last edited dcterms:modified
name Official facility name institutionID
postalcode Facility ZIP/Postal Code institutionID
stateprov Facility State or Province institutionID
Media Group
copyright_info Copyright holder dcterms:accessRights
copyright_license License governing the terms of use/resuse of the media dcterms:accessRights
copyright_permission Specific rights granted for use or reuse of the media dcterms:accessRights
derived_from_media_id MorphoSource identifier of media group record was derived from associatedMedia
created_on Date of creation for the media record N/A
element The anatomical element depicted in the media associatedMedia
grant_support The names of supporting institutions and identifiers for grants which supported creation of the media dcterms:bibliographicCitation
is_copyrighted Flag indicating the copyright status of the media. "1" indicates that it is copyrighted, "0" that it is not. dcterms:accessRights
last_modified_on Date the media record was last changed dcterms:modified
media_citation_instruction1-3 Fields containing additional information pertaining to the formal citation language dcterms:bibliographicCitations
media_id MorphoSource identifier for this media record datasetID
notes General notes describing the media associatedMedia
published Publication status dcterms:accessRights
published_on Date on which the media record was published in MorphoSource N/A
scanner_acquisition_time Acquisition Time measurement
scanner_amperage Amperage, units in microAmps measurement
scanner_calibration_description Calibration Description measurement
scanner_calibration_flux_normalization Flux Normalization Calibration measurement
scanner_calibration_geometric_calibration Geometric Calibration measurement
scanner_calibration_shading_correction Shading Correction Calibration measurement
scanner_exposure_time Exposure time, units in seconds measurement
scanner_filter Filter measurement
scanner_frame_averaging Frame Averaging. The number of images acquired at each projection angle and their average measurement
scanner_id Unique MorphoSource identifier for scanner measurementID
scanner_name Name of scanner measurement
scanner_projections Projections. The number of images at distinct angles used to create a 3D image measurement
scanner_technicians Individual(s) responsible for scanning & uploading the specimen measurement
scanner_voltage Voltage, units in kilovolts measurement
scanner_watts Watts (power = kV*Amps) measurement
scanner_wedge Wedge measurement
scanner_x_resolution X-Axis Resolution measurement
scanner_y_resolution Y-Axis Resolution measurement
scanner_z_resolution Z-Axis Resolution measurement
side The anatomical side of the organism that the media group represents when applicable associatedMedia
specimen_institution_code Unique code identifying an institution institutionCode
specimen_collection_code Code identifying institutional collection specimen resides in collectionCode
specimen_catalog_number Unique alphanumeric string identifying a specimen within a repository and subcollection catalogNumber
specimen_specimen_id Unique MorpoSource identifier for the specimen occurrenceID
title Title of media group datasetName
Media File
doi Global unique identifier for the media file dcterms:references
download If enabled, a link to download the media file from MorphoSource associatedMedia
element The anatomical element depicted by the media file associatedMedia
file_type Raw file of group or derivative file
filesize Size of the file in mebibyte (MiB) associatedMedia
notes Media file notes
media_file_id MorphoSource identifier for media file
mimetype Identifier for file format (e.g. "application/ply" or "image/tiff") associatedMedia
published Publication status (supersedes that of the media group) dcterms:accessRights
published_on Date on which the media file record was published on MorphoSource N/A
side The anatomical side of the organism that the element represents, when applicable associatedMedia
title Formal, descriptive, title of the media file associatedMedia
Projects
abstract A general description of the goals and scope of the project dcterms:bibliographicCitation
created_on Date the project was created in MorphoSource N/A
last_modified_on Date the project was last modified in MorphoSource dcterms:modified
name Official name of the project datasetName/dcterms:bibliographicCitation
project_id Unique identifer for the project within MorphoSource datasetID
published_on Date on which the project was published N/A
url Link to an external page describing or containing other information concerning the project, or DOI uniquely identifying the resource dcterms:reference
Taxonomy
author Scientific Name Author scientificNameAuthorship
created_on Date taxonomy was created in MorphoSource N/A
ht_kingdom Kingdom kingdom
ht_phylum Phylum phylum
ht_class Class class
ht_subclass Subclass higherClassification
ht_superorder Superorder higherClassification
ht_order Order order
ht_suborder Suborder higherClassification
ht_superfamily Superfamily higherClassification
ht_family Family family
ht_subfamily Subfamily higherClassification
genus Genus genus
ht_supraspecific_clade Supraspecific clade higherClassification
species Species specificEpithet
subspecies Subspecies infraspecificEpithet
variety Variety infraspecificEpithet
is_extinct Flag that indicates if the subject of the current taxonomy is extinct taxonRemarks
last_modified_on Date taxonomy was last modified dcterms:modified
notes General remarks pertaining to the Taxonomy taxonRemarks
taxon_id Unique MorphoSource identifier for the taxonomy taxonID
year Year of Authorship namePublishedInYear
Facility Scanners
description General description of the scanner institutionID
facility_id MorphoSource ID for facility institutionID
name Make & Model of the scanner institutionID
Institutions
city City institutionID
county County institutionID
description Description of the institution institutionID
name Formal name of the institution institutionID
state State institutionID
Bibliography
abstract Article Abstract dcterms:references
article_title Article Tite dcterms:references
authors Article Authors dcterms:references
collation Collation dcterms:references
created_on Date record created for this resource N/A
description Article Description dcterms:references
editors Editors dcterms:references
eletronic_resource_number An externally assigned reference (usually a DOI) dcterms:references
external_identifer An externally assigned reference (usually a DOI) dcterms:references
isbn ISBN dcterms:references
journal_title Journal Title dcterms:references
keywords Keywords dcterms:references
language Language dcterms:references
last_modified_on Date this record was last modified dcterms:modified
monograph_title Monography Title dcterms:references
page_number Total page count dcterms:references
publication_place Place of Publication dcterms:references
publication_year Year of Publication dcterms:references
publisher Publisher dcterms:references
reference_type Reference Type dcterms:references
secondary_authors Secondary Article Authors dcterms:references
secondary_title Secondary Article Title dcterms:references
section Section dcterms:references
url Article URL dcterms:references
volume Journal Volume dcterms:references
worktype Worktype dcterms:references