Using the API

All API functions are accessed using URLs in the form

http://www.morphobank.org/service.php/[command]/[resource type]?[url-encoded parameter list]

where [command] is an API function and [resource type] is one of the following: PublishedProjects, ProjectMedia, ProjectTaxonomy. [url-encoded parameter list] is an HTTP query string containing command options.

The API presently includes a single command, List, that comprehensive lists of published MorphoBank data by project.

The API response

The API List command will return a JSON object similar to this one:

{		
    "ok": true,
    "totalResults": 305,
    "parameters": {
        "project_id": "44"
    },
    "results": [
        {
            "media_id": "31",
            "view": "adenostyle",
            "taxon_id": "313",
            "taxonomy": "Parasiro minor",
            "specimen_id": "25",
            "specimen": "Parasiro minor (MHNG)",
            "is_copyrighted": "Yes",
            "copyright_permission": "Permission to use media on MorphoBank granted by copyright holder",
            "copyright_license": "Attribution- CC BY-NC-SA - reuse here and applied to future uses but noncommercial",
            "copyright_holder": "Gonzalo Giribet",
            "notes": "Image by Gonzalo Giribet\r\nImage edited by Jessica Tupper",
            "web_source": "",
            "web_source_description": "",
            "citation": "",
            "url": "https://morphobank.org/index.php/Projects/Media/id/31/project_id/44"
        },
        ...and 305 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 error property will include a description of the error. The totalResults property will indicate the total number of resources found. The parameters object includes a summary of any parameters passed to the command.

The results property, contains a list of JSON objects representing each returned resource.

Examples

Return a list of all published MorphoBank projects

https://morphobank.org/service.php/List/PublishedProjects

{
	
    "ok": true,
    "status": "ok",
    "totalResults": 515,
    "results": [
        {
            "project_id": "44",
            "name": "New genus of cyphophthalmid from the Iberian Peninsula with a phylogenetic analysis of the Sironidae (Arachnida: Opiliones: Cyphophthalmi) and a SEM database of external morphology",
            "media_count": 309,
            "taxonomy_count": 30,
            "matrices_count": 1,
            "url": "https://morphobank.org/index.php/Projects/ProjectOverview/project_id/44"
        },
        {
            "project_id": "45",
            "name": "Cretaceous Myliobatids from Mali",
            "media_count": 187,
            "taxonomy_count": 55,
            "matrices_count": 1,
            "url": "https://morphobank.org/index.php/Projects/ProjectOverview/project_id/45"
        },
        ...and 513 more...
    ]
}
		

Return a list of project taxonomy

https://morphobank.org/service.php/List/ProjectTaxonomy?project_id=44

ProjectTaxonomy requires the following parameter:
project_id is the unique, numberic identifier of the project to find media for

{

    "ok": true,
    "status": "ok",
    "totalResults": 30,
    "parameters": {
        "project_id": "44"
    },
    "results": [
        {
            "taxon_id": "300",
            "is_extinct": "0",
            "genus": "Stylocellus",
            "specific_epithet": "globosus",
            "supraspecific_clade": "",
            "higher_taxon_kingdom": "",
            "higher_taxon_phylum": "",
            "higher_taxon_class": "",
            "higher_taxon_subclass": "",
            "higher_taxon_infraclass": "",
            "higher_taxon_cohort": "",
            "higher_taxon_superorder": "",
            "higher_taxon_order": "",
            "higher_taxon_suborder": "",
            "higher_taxon_infraorder": "",
            "higher_taxon_superfamily": "",
            "higher_taxon_family": "",
            "higher_taxon_subfamily": "",
            "higher_taxon_tribe": "",
            "higher_taxon_subtribe": "",
            "subgenus": "",
            "subspecific_epithet": "",
            "scientific_name_author": "",
            "scientific_name_year": "0",
            "use_parens_for_author": "0",
            "notes": "",
            "scientific_name": "Stylocellus globosus",
            "usage": {
                "total": 17,
                "media": 15,
                "specimens": "1",
                "bibliographic_references": "0",
                "partitions": "0",
                "matrices": "1"
            },
            "citation": ""
        },
        ...and 29 more...
    ]
}
		

Return a list of project media

https://morphobank.org/service.php/List/ProjectMedia?project_id=44

ProjectMedia requires the following 2 parameters:
project_id is the unique, numberic identifier of the project to find media for

{

    "ok": true,
    "status": "ok",
    "totalResults": 305,
    "parameters": {
        "project_id": "44"
    },
    "results": [
        {
            "media_id": "31",
            "view": "adenostyle",
            "taxon_id": "313",
            "taxonomy": "Parasiro minor",
            "specimen_id": "25",
            "specimen": "Parasiro minor (MHNG)",
            "is_copyrighted": "Yes",
            "copyright_permission": "Permission to use media on MorphoBank granted by copyright holder",
            "copyright_license": "Attribution- CC BY-NC-SA - reuse here and applied to future uses but noncommercial",
            "copyright_holder": "Gonzalo Giribet",
            "notes": "Image by Gonzalo Giribet\r\nImage edited by Jessica Tupper",
            "web_source": "",
            "web_source_description": "",
            "citation": "",
            "url": "https:\/\/morphobank.org\/index.php\/Projects\/Media\/id\/31\/project_id\/44"
        }
    	...and 304 more...
    ]
}