- This document contains data shared through the GBIF Network - see http://data.gbif.org/ for more information. All usage of these data must be in accordance with the GBIF Data Use Agreement - see http://www.gbif.org/DataProviders/Agreements/DUA - - HELP CONTENTS 1. SUMMARY 2. GET INDIVIDUAL RECORDS - get 3. SEARCH FOR RECORDS - list 4. COUNT RECORDS - count 5. GET HELP - help 6. RESPONSE STRUCTURE - schema 7. BROWSER FORMATTING - stylesheet 1. SUMMARY The provider web service provides access to records describing the data providers in the GBIF network. Syntax: http://data.gbif.org/ws/rest/provider/<action>?<parameter_list> where: action is one of: get - get a single provider record list - search for provider records matching a range of filters count - count provider records matching a range of filters help - displays this help text schema - returns the response schema document stylesheet - returns a stylesheet for rendering response documents as HTML parameter_list is a set of key-value pair options controlling or modifying how the service handles the action request. See subsections below for information on the parameters supported in parameter list for each action. 2. GET INDIVIDUAL RECORDS - get Syntax: http://data.gbif.org/ws/rest/provider/get/<key>?<parameter_list> or: http://data.gbif.org/ws/rest/provider/get?<parameter_list> where: key is a numeric key uniquely identifying the provider record within the GBIF data portal. parameter_list is a set of URL-encoded key-value pairs including any of the following keys: key - numeric key uniquely identifying the provider record within the GBIF data portal (same as key above) stylesheet - sets the URL of the stylesheet to be associated with the response document. This overrides the default provided by the data portal. Supplying an empty string as the value for this parameter disables the setting of a stylesheet by the data portal. The value of this parameter is used in an xml-stylesheet processing instruction at the start of the response document. See "7. BROWSER FORMATTING - stylesheet" below. The get action is intended as a quick way to retrieve a provider record for which the key is already known (e.g. from an earlier use of the list action). The response is formatted according to the XML schema returned by the schema action (see "6. RESPONSE STRUCTURE - schema" below). Examples: http://data.gbif.org/ws/rest/provider/get/100 - returns the provider record with key 100 http://data.gbif.org/ws/rest/provider/get?key=100&stylesheet= - returns the provider record with key 100 with HTML formatting disabled. 3. SEARCH FOR RECORDS - list Syntax: http://data.gbif.org/ws/rest/provider/list?<parameter_list> where: parameter_list is a set of URL-encoded key-value pairs including any of the following keys: name - return only providers with names starting with the supplied string. isocountrycode - return only providers from the country identified by the supplied 2-letter ISO code. modifiedsince - return only records which have been indexed or modified in the GBIF data portal index on or after the supplied date (format YYYY-MM-DD, e.g. 2006-11-28). Note that these dates are based on the time at the GBIF Secretariat in Copenhagen. startindex - return the subset of the matching records that starts at the supplied (zero-based index). If this is not supplied, the response includes records starting with the first matching record (equivalent to startindex=0). This can be used in conjunction with information in the /gbifResults/header/summary element in the response document to manage paging through large sets of records. maxresults - return at most the specified number of records. The default (and maximum supported) is 1000 records. stylesheet - sets the URL of the stylesheet to be associated with the response document. This overrides the default provided by the data portal. Supplying an empty string as the value for this parameter disables the setting of a stylesheet by the data portal. The value of this parameter is used in an xml-stylesheet processing instruction at the start of the response document. See "7. BROWSER FORMATTING - stylesheet" below. The list action should be used to find provider records of interest from within the GBIF data portal. Note that this action does not count all records in the portal matching the supplied filters. The totalMatched attribute in the response should only be used to indicate whether further records exist. To get an accurate total count, us the count action (see "4. COUNT RECORDS - count" below). The response is formatted according to the XML schema returned by the schema action (see "6. RESPONSE STRUCTURE - schema" below. The provider records are found in the response document at the path /gbifResponse/dataProvider/dataProvider The /gbifResponse/header/summary element may contain up to four attributes: start - the index of the first matching record returned. totalMatched - the minimum number of matching records contained in the portal. This should only be used to indicate that there are more records still unreturned. Use the count action for an accurate count. This value is only reliable if the startindex on the request was lower than the number of records actually matching. totalReturned - the number of records actually returned in this response. next - the index of the next matching record (if totalMatched is greater than totalReturned). This can be used as the value for startindex on the next list request to retrieve another page of matching records. When there are more matching records to retrieve (i.e. the next attribute is set), the document includes a URL which can be used to retrieve the next page. This is returned in the /gbifResponse/header/nextRequestUrl element. Examples: http://data.gbif.org/ws/rest/provider/list?name=Can - returns records for providers with names beginning with the string "Can" http://data.gbif.org/ws/rest/provider/list?originisocountrycode=US - returns records for providers from the US Likely future enhancements: 1. Support multiple values for a single parameter (to be OR'ed together). 4. COUNT RECORDS - count Syntax: http://data.gbif.org/ws/rest/provider/count?<parameter_list> where: parameter_list is a set of URL-encoded key-value pairs including any of the following keys: name - count only providers with names starting with the supplied string. isocountrycode - count only providers from the country identified by the supplied 2-letter ISO code. modifiedsince - count only records which have been indexed or modified in the GBIF data portal index on or after the supplied date (format YYYY-MM-DD, e.g. 2006-11-28). Note that these dates are based on the time at the GBIF Secretariat in Copenhagen. stylesheet - sets the URL of the stylesheet to be associated with the response document. This overrides the default provided by the data portal. Supplying an empty string as the value for this parameter disables the setting of a stylesheet by the data portal. The value of this parameter is used in an xml-stylesheet processing instruction at the start of the response document. See "7. BROWSER FORMATTING - stylesheet" below. The count action can be used to get an accurate count of provider records of interest from within the GBIF data portal prior to retrieving these records using the list action. This may assist with deciding whether to refine the search more closely before retrieving records. The response is formatted according to the XML schema returned by the schema action (see "6. RESPONSE STRUCTURE - schema" below). The count is returned in the totalMatched attribute of the /gbifResponse/header/summary element in the response document. Examples: http://data.gbif.org/ws/rest/provider/count?isocountrycode=CA - counts providers from Canada Likely future enhancements: 1. Support multiple values for a single parameter (to be OR'ed together). 5. GET HELP - help Syntax: http://data.gbif.org/ws/rest/provider/help or: http://data.gbif.org/ws/rest/provider The help action returns this help documentation. 6. RESPONSE STRUCTURE - schema Syntax: http://data.gbif.org/ws/rest/provider/schema The schema action returns the XML schema document used for the responses to the get, list, count and help actions. The response document includes a header which includes intellectual property statements, information on the request issued and a summary of the response contents. The body of the document for the response to a list or get action request is a dataProviders element, containing one or more dataProvider elements with metadata on a particular resource and a set of matching records. 7. BROWSER FORMATTING - stylesheet Syntax: http://data.gbif.org/ws/rest/provider/stylesheet The stylesheet action returns a simple XSLT document which can be used to display the responses to the get, list, count and help actions in a readable form in a web browser. An xml-stylesheet processing instruction referenceing this stylesheet is included by default in the responses to these actions. - help