GET Institutions - nybgvh/IH-API GitHub Wiki

Get all Institutions

Resource URL

/v1/institutions

Sample Request

http://sweetgum.nybg.org/science/api/v1/institutions

Search for an Institution by code

Resource URL

/v1/institutions/{code}

Sample Request

http://sweetgum.nybg.org/science/api/v1/institutions/hk

Sample Response

{
	"irn": 123921,
	"organization": "Agriculture, Fisheries, and Conservation Department",
	"code": "HK",
	"division": "",
	"department": "",
        "cites": "",
	"specimenTotal": 42054,
        "currentStatus": "Active",
        "dateFounded": "1878",
        "taxonomicCoverage": "",
        "geography": "Hong Kong and surrounding areas",
	"address": {
		"physicalStreet": "",
		"physicalCity": "Hong Kong",
		"physicalState": "Hong Kong",
		"physicalZipCode": "",
		"physicalCountry": "People's Republic of China",
		"postalStreet": "303 Cheung Sha Wan Road, Room 737, Cheung Sha Wan Government Offices",
		"postalCity": "Kowloon",
		"postalState": "Hong Kong",
		"postalZipCode": "",
		"postalCountry": "People's Republic of China"
	},
	"contact": {
		"phone": "[852] 2150 6900",
		"email": "[email protected]",
		"webUrl": "http://www.herbarium.gov.hk/"
	},
	"location": {
		"lat": 22.322702,
		"lon": 114.18721
	},
}

Search Institutions by record property

Returns a list of institutions matching a search term.

Resource URL

/v1/institutions/search

Parameters

Name	Data Type	Description
city	string	Search institutions by city (e.g. "milwakee")
state	string	Search institutions by state (e.g. "new york")
country	string	Search institutions by country (e.g. "india")
organization	string	Search institutions by name (e.g. "new york state museum")
code	string	Search institutions by code (e.g. "ala")
sort	string	Sort results (values: "organization", "code", "city", "state", "country", "specimenTotal")
limit	number	Specify the number of records to return (e.g. 50)
dateModified	string	Date of the last modification of the record. (mm/dd/yyyy Format, operators: <, >) (e.g. ">10/6/2015")
download	string	Download as CSV File (value: "yes")

Sample Request

http://sweetgum.nybg.org/science/api/v1/institutions/search?country=u.s.a.&state=new%20york

http://sweetgum.nybg.org/science/api/v1/institutions/search?state=new%20york&limit=10&sort=specimenTotal

http://sweetgum.nybg.org/science/api/v1/institutions/search?dateModified=>1/30/2015&country=india

http://sweetgum.nybg.org/science/api/v1/institutions/search?state=california&download=yes

Sample Response

{
	"meta": {
	"hits": 1,
	"code": 200
	},
	"data": [
	    {
		"irn": 126584,
		"organization": "University of Alaska Museum of the North",
		"code": "ALA",
		"division": "",
		"department": "",
                "cites": "US 130",
		"specimenTotal": 200000,
                "currentStatus": "Active",
                "dateFounded": "1962",
                "taxonomicCoverage": "Vascular plants, lichens, bryophytes, and marine algae of Alaska",
                "geography": "Circumpolar north; Siberia and Russian Far East",
		"address": {
			"physicalStreet": "",
			"physicalCity": "Fairbanks",
			"physicalState": "Alaska",
			"physicalZipCode": "",
			"physicalCountry": "U.S.A.",
			"postalStreet": "P.O. Box 756960, 1962 Yukon Drive",
			"postalCity": "Fairbanks",
			"postalState": "Alaska",
			"postalZipCode": "99775-6960",
			"postalCountry": "U.S.A."
		},
		"contact": {
			"phone": "[1] 907 474 7109",
			"email": "[email protected]",
			"webUrl": "http://www.uaf.edu/museum/collections/herb/"
		},
		"location": {
			"lat": 64.858009,
			"lon": -147.838211
		},
	    }
	]
}

Nearby Search Requests

Returns a list of institutions within a specified area.

Resource URL

/v1/institutions/nearbysearch

Parameters

Name	Data Type	Description
lat	decimal	Required. Latitude of the location you want to search nearby.
lon	decimal	Required. Longitude of the location you want to search nearby.
radius	decimal	Optional. Search radius in miles. By default, radius is 15. Maximum is 50.

Sample Request

http://sweetgum.nybg.org/science/api/v1/institutions/nearbysearch?lat=40.670898&lon=-73.927948&radius=10.5

Response Values

Name	Data Type	Description
irn	number	Unique institution identifier for IH record (e.g. http://sweetgum.nybg.org/science/ih/herbarium-details/?irn=127029)
organization	string	Name of this institution
code	string	Unique code for this institution
division	string	Division for this institution
department	string	Department for this institution
cites	string	CITES for this institution
specimenTotal	string	Total specimens for this institution
currentStatus	string	Current status for this institution
dateFounded	string	Date founded for this institution
taxonomicCoverage	string	Taxonomic coverage for this institution
geography	string	Geography range for this institution
address	dict	Address data for this institution
address.physicalStreet	string	Physical street address for this institution
address.physicalCity	string	Physical city for this institution
address.physicalState	string	Physical state for this institution
address.physicalZipCode	string	Physical zip code for this institution
address.physicalCountry	string	Physical country for this institution
address.postalStreet	string	Postal street address for this institution
address.postalCity	string	Postal city for this institution
address.postalState	string	Postal state for this institution
address.postalZipCode	string	Postal zip code for this institution
address.postalCountry	string	Postal country for this institution
contact	dict	Contact data for this institution
contact.phone	string	Phone number for this institution
contact.email	string	Email for this institution
contact.webUrl	string	URL for this institution page
location	dict	Location data for this institution
location.lat	decimal	Latitude position
location.lon	decimal	Longitude position
collectionsSummary	dict	A summary of total specimens stored in this institution
collectionsSummary.numAlgae	number	Total number of Algae
collectionsSummary.numAlgaeDatabased	number	Total number of Algae databased
collectionsSummary.numAlgaeImaged	number	Total number of Algae imaged
collectionsSummary.numBryos	number	Total number of Bryophytes
collectionsSummary.numBryosDatabased	number	Total number of Bryophytes databased
collectionsSummary.numBryosImaged	number	Total number of Bryophytes imaged
collectionsSummary.numFungi	number	Total number of Fungi/Lichens
collectionsSummary.numFungiDatabased	number	Total number of Fungi/Lichens databased
collectionsSummary.numFungiImaged	number	Total number of Fungi/Lichens imaged
collectionsSummary.numPteridos	number	Total number of Pteridophytes
collectionsSummary.numPteridosDatabased	number	Total number of Pteridophytes databased
collectionsSummary.numPteridosImaged	number	Total number of Pteridophytes imaged
collectionsSummary.numSeedPl	number	Total number of Seed Plants
collectionsSummary.numSeedPlDatabased	number	Total number of Seed Plants databased
collectionsSummary.numSeedPlImaged	number	Total number of Seed Plants imaged
incorporatedHerbaria	string[]	List of incorporated herbaria
importantCollectors	string[]	List of important collectors
notes	string	Notes about this institution
dateModified	string	Date of the last modification of the record
distance	decimal	Distance in miles within a specified area (nearby search)

Javascript

Make a Javascript AJAX request:

     $.ajax({
            url: 'http://sweetgum.nybg.org/science/api/v1/institutions/search',
            dataType: 'json',
            type: 'GET',
	    data: {dateModified: ">1/30/2015", country:"india"},
            success: function(res){
		$.each(res.data, function(index, element){
		    $('#herbarium').append(element.organization + '<br>');
		});
            }
     });

PHP

Using the API with PHP:

      $url = "http://sweetgum.nybg.org/science/api/v1/institutions/search?country=india";
 
      $curl = curl_init();
      curl_setopt_array($curl, array(
         CURLOPT_RETURNTRANSFER => 1,
         CURLOPT_URL => $url
      ));

      $response = curl_exec($curl);
      curl_close($curl);
      $json = json_decode($response);

      foreach( $json->data as $org )
      {
         echo $org->organization . '<br>';
      }

R

Using the API with R:

      library(jsonlite)
      url <- "http://sweetgum.nybg.org/science/api/v1/institutions/search?country=india"
      df <- fromJSON(url)$data
      df$organization