def get_occurrence_search_collection_code(self,
options=dict()):
"""Does a GET request to /occurrence/search/collectionCode.
Search that returns matching collection codes. Results are ordered by
relevance.
Args:
options (dict, optional): Key-value pairs for any of the
parameters to this API Endpoint. All parameters to the
endpoint are supplied through the dictionary with their names
being the key and their desired values being the value. A list
of parameters that can be used are::
limit -- int -- The maximum number of results to return.
This can't be greater than 300, any value greater is
set to 300.
q -- string -- Simple search parameter. The value for this
parameter can be a simple word or a phrase.
Returns:
mixed: Response from the API.
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# The base uri for api requests
query_builder = Configuration.BASE_URI
# Prepare query string for API call
query_builder += "/occurrence/search/collectionCode"
# Process optional query parameters
query_builder = APIHelper.append_url_with_query_parameters(query_builder, {
"limit": options.get('limit', None),
"q": options.get('q', None)
})
# Validate and preprocess url
query_url = APIHelper.clean_url(query_builder)
# Prepare headers
headers = {
"user-agent": "APIMATIC 2.0",
"accept": "application/json"
}
# Prepare and invoke the API call request to fetch the response
response = unirest.get(query_url, headers=headers)
# Error handling using HTTP status codes
if response.code < 200 or response.code > 206: # 200 = HTTP OK
raise APIException("HTTP Response Not OK", response.code, response.body)
return response.body
def get_occurrence_inventories_list_count_by_pub_country(self,
country):
"""Does a GET request to /occurrence/counts/publishingCountries.
Lists occurrence counts for all countries that publish data about the
given country.
Args:
country (string): The 2-letter country code (as per ISO-3166-1) of
the country in which the occurrence was recorded.
Returns:
mixed: Response from the API.
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# The base uri for api requests
query_builder = Configuration.BASE_URI
# Prepare query string for API call
query_builder += "/occurrence/counts/publishingCountries"
# Process optional query parameters
query_builder = APIHelper.append_url_with_query_parameters(query_builder, {
"country": country
})
# Validate and preprocess url
query_url = APIHelper.clean_url(query_builder)
# Prepare headers
headers = {
"user-agent": "APIMATIC 2.0",
"accept": "application/json"
}
# Prepare and invoke the API call request to fetch the response
response = unirest.get(query_url, headers=headers)
# Error handling using HTTP status codes
if response.code < 200 or response.code > 206: # 200 = HTTP OK
raise APIException("HTTP Response Not OK", response.code, response.body)
return response.body
def get_occurrence_get_verbatim(self, key):
"""Does a GET request to /occurrence/{key}/verbatim.
Gets the verbatim occurrence record without any interpretation
Args:
key (int): Gets the verbatim occurrence record without any
interpretation
Returns:
VerbatimOccurrence: Response from the API.
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# The base uri for api requests
query_builder = Configuration.BASE_URI
# Prepare query string for API call
query_builder += "/occurrence/{key}/verbatim"
# Process optional template parameters
query_builder = APIHelper.append_url_with_template_parameters(query_builder, {"key": key})
# Validate and preprocess url
query_url = APIHelper.clean_url(query_builder)
# Prepare headers
headers = {"user-agent": "APIMATIC 2.0", "accept": "application/json"}
# Prepare and invoke the API call request to fetch the response
response = unirest.get(query_url, headers=headers)
# Error handling using HTTP status codes
if response.code < 200 or response.code > 206: # 200 = HTTP OK
raise APIException("HTTP Response Not OK", response.code, response.body)
# Try to cast response to desired type
if isinstance(response.body, dict):
# Response is already in a dictionary, return the object
return VerbatimOccurrence(**response.body)
# If we got here then an error occured while trying to parse the response
raise APIException("Invalid JSON returned", response.code, response.body)
def get_occurrence_download_metadata_by_key(self,
key):
"""Does a GET request to /occurrence/download/{key}.
Retrieves the occurrence download metadata by its unique key.
Args:
key (string): Retrieves the occurrence download metadata by its
unique key.
Returns:
mixed: Response from the API.
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# The base uri for api requests
query_builder = Configuration.BASE_URI
# Prepare query string for API call
query_builder += "/occurrence/download/{key}"
# Process optional template parameters
query_builder = APIHelper.append_url_with_template_parameters(query_builder, {
"key": key
})
# Validate and preprocess url
query_url = APIHelper.clean_url(query_builder)
# Prepare headers
headers = {
"user-agent": "APIMATIC 2.0",
"accept": "application/json"
}
# Prepare and invoke the API call request to fetch the response
response = unirest.get(query_url, headers=headers)
# Error handling using HTTP status codes
if response.code < 200 or response.code > 206: # 200 = HTTP OK
raise APIException("HTTP Response Not OK", response.code, response.body)
return response.body
def get_occurrence_inventories_list_count_by_year(self,
year):
"""Does a GET request to /occurrence/counts/year.
Lists occurrence counts by year.
Args:
year (string): The 4 digit year. A year of 98 will be interpreted
as AD 98. Supports range queries.
Returns:
mixed: Response from the API.
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# The base uri for api requests
query_builder = Configuration.BASE_URI
# Prepare query string for API call
query_builder += "/occurrence/counts/year"
# Process optional query parameters
query_builder = APIHelper.append_url_with_query_parameters(query_builder, {
"year": year
})
# Validate and preprocess url
query_url = APIHelper.clean_url(query_builder)
# Prepare headers
headers = {
"user-agent": "APIMATIC 2.0",
"accept": "application/json"
}
# Prepare and invoke the API call request to fetch the response
response = unirest.get(query_url, headers=headers)
# Error handling using HTTP status codes
if response.code < 200 or response.code > 206: # 200 = HTTP OK
raise APIException("HTTP Response Not OK", response.code, response.body)
return response.body
def update_occurrence_download_put_update_status(self,
key):
"""Does a PUT request to /occurrence/download/{key}.
Updates the status of an existing occurrence download. This operation
can be executed by the role ADMIN only.
Args:
key (string): Updates the status of an existing occurrence
download.
Returns:
void: Response from the API.
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# The base uri for api requests
query_builder = Configuration.BASE_URI
# Prepare query string for API call
query_builder += "/occurrence/download/{key}"
# Process optional template parameters
query_builder = APIHelper.append_url_with_template_parameters(query_builder, {
"key": key
})
# Validate and preprocess url
query_url = APIHelper.clean_url(query_builder)
# Prepare headers
headers = {
"user-agent": "APIMATIC 2.0"
}
# Prepare and invoke the API call request to fetch the response
response = unirest.put(query_url, headers=headers, params={}, auth=(self.__user, self.__password))
# Error handling using HTTP status codes
if response.code < 200 or response.code > 206: # 200 = HTTP OK
raise APIException("HTTP Response Not OK", response.code, response.body)
def resolve_names(self):
"""Creates a dictionary representation of this object.
This method converts an object to a dictionary that represents the
format that the model should be in when passed into an API Request.
Because of this, the generated dictionary may have different
property names to that of the model itself.
Returns:
dict: The dictionary representing the object.
"""
# Create a mapping from Model property names to API property names
replace_names = {
"key": "key",
"datasetkey": "datasetkey",
"publishing_org_key": "publishingOrgKey",
"publishing_country": "publishingCountry",
"protocol": "protocol",
"last_crawled": "lastCrawled",
"basis_of_record": "basisOfRecord",
"decimal_longitude": "decimalLongitude",
"decimal_latitude": "decimalLatitude",
"continent": "continent",
"year": "year",
"month": "month",
"day": "day",
"event_date": "eventDate",
"issues": "issues",
"last_interpreted": "lastInterpreted",
"identifiers": "identifiers",
"facts": "facts",
"relations": "relations",
"geodetic_datum": "geodeticDatum",
"country_code": "countryCode",
"country": "country",
"gbif_id": "gbifID",
"institution_code": "institutionCode",
"catalog_number": "catalogNumber",
"recorded_by": "recordedBy",
"locality": "locality",
"collection_code": "collectionCode",
"identified_by": "identifiedBy",
}
retval = dict()
return APIHelper.resolve_names(self, replace_names, retval)
def resolve_names(self):
"""Creates a dictionary representation of this object.
This method converts an object to a dictionary that represents the
format that the model should be in when passed into an API Request.
Because of this, the generated dictionary may have different
property names to that of the model itself.
Returns:
dict: The dictionary representing the object.
"""
# Create a mapping from Model property names to API property names
replace_names = {
"key": "key",
"dataset_key": "datasetKey",
"publishing_org_key": "publishingOrgKey",
"publishing_country": "publishingCountry",
"protocol": "protocol",
"last_crawled": "lastCrawled",
"http_rs_tdwg_org_dwc_terms_day": "http://rs.tdwg.org/dwc/terms/day",
"http_rs_gbif_org_terms_1_0_gbif_id": "http://rs.gbif.org/terms/1.0/gbifID",
"http_rs_tdwg_org_dwc_terms_continent": "http://rs.tdwg.org/dwc/terms/continent",
"http_rs_tdwg_org_dwc_terms_country": "http://rs.tdwg.org/dwc/terms/country",
"http_rs_tdwg_org_dwc_terms_collection_code": "http://rs.tdwg.org/dwc/terms/collectionCode",
"http_rs_tdwg_org_dwc_terms_year": "http://rs.tdwg.org/dwc/terms/year",
"http_rs_tdwg_org_dwc_terms_locality": "http://rs.tdwg.org/dwc/terms/locality",
"http_rs_tdwg_org_dwc_terms_identified_by": "http://rs.tdwg.org/dwc/terms/identifiedBy",
"http_rs_tdwg_org_dwc_terms_verbatim_latitude": "http://rs.tdwg.org/dwc/terms/verbatimLatitude",
"http_rs_tdwg_org_dwc_terms_basis_of_record": "http://rs.tdwg.org/dwc/terms/basisOfRecord",
"http_rs_tdwg_org_dwc_terms_verbatim_longitude": "http://rs.tdwg.org/dwc/terms/verbatimLongitude",
"http_rs_tdwg_org_dwc_terms_catalog_number": "http://rs.tdwg.org/dwc/terms/catalogNumber",
"http_rs_tdwg_org_dwc_terms_month": "http://rs.tdwg.org/dwc/terms/month",
"http_rs_tdwg_org_dwc_terms_institution_code": "http://rs.tdwg.org/dwc/terms/institutionCode",
"http_rs_tdwg_org_dwc_terms_coordinate_precision": "http://rs.tdwg.org/dwc/terms/coordinatePrecision",
"http_rs_tdwg_org_dwc_terms_recorded_by": "http://rs.tdwg.org/dwc/terms/recordedBy",
"http_rs_tdwg_org_dwc_terms_scientific_name": "http://rs.tdwg.org/dwc/terms/scientificName",
}
retval = dict()
return APIHelper.resolve_names(self, replace_names, retval)
def create_occurrence_download_post_request(self):
"""Does a POST request to /occurrence/download/request.
Starts the process of creating a download file. See the predicates
section to consult the requests accepted by this service.
Returns:
string: Response from the API.
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# The base uri for api requests
query_builder = Configuration.BASE_URI
# Prepare query string for API call
query_builder += "/occurrence/download/request"
# Validate and preprocess url
query_url = APIHelper.clean_url(query_builder)
# Prepare headers
headers = {
"user-agent": "APIMATIC 2.0"
}
# Prepare and invoke the API call request to fetch the response
response = unirest.post(query_url, headers=headers, params={}, auth=(self.__user, self.__password))
# Error handling using HTTP status codes
if response.code < 200 or response.code > 206: # 200 = HTTP OK
raise APIException("HTTP Response Not OK", response.code, response.body)
return response.body
def get_occurrence_metrics_count_schema(self):
"""Does a GET request to /occurrence/count/schema.
List the supported metrics by the service.
Returns:
mixed: Response from the API.
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# The base uri for api requests
query_builder = Configuration.BASE_URI
# Prepare query string for API call
query_builder += "/occurrence/count/schema"
# Validate and preprocess url
query_url = APIHelper.clean_url(query_builder)
# Prepare headers
headers = {
"user-agent": "APIMATIC 2.0",
"accept": "application/json"
}
# Prepare and invoke the API call request to fetch the response
response = unirest.get(query_url, headers=headers)
# Error handling using HTTP status codes
if response.code < 200 or response.code > 206: # 200 = HTTP OK
raise APIException("HTTP Response Not OK", response.code, response.body)
return response.body
def resolve_names(self):
"""Creates a dictionary representation of this object.
This method converts an object to a dictionary that represents the
format that the model should be in when passed into an API Request.
Because of this, the generated dictionary may have different
property names to that of the model itself.
Returns:
dict: The dictionary representing the object.
"""
# Create a mapping from Model property names to API property names
replace_names = {
"observations": "Observations",
"specimens": "Specimens",
"living": "Living",
"fossil": "Fossil",
"other": "Other",
}
retval = dict()
return APIHelper.resolve_names(self, replace_names, retval)
def get_occurrence_download_list(self,
options=dict()):
"""Does a GET request to /occurrence/download/dataset/{datasetKey}.
Lists the downloads activity of a dataset.
Args:
options (dict, optional): Key-value pairs for any of the
parameters to this API Endpoint. All parameters to the
endpoint are supplied through the dictionary with their names
being the key and their desired values being the value. A list
of parameters that can be used are::
dataset_key -- string -- Lists the downloads activity of
dataset.
limit -- int -- Controls the number of results in the
page. Using too high a value will be overwritten with
the default maximum threshold, depending on the
service. Sensible defaults are used so this may be
omitted.
offset -- int -- Determines the offset for the search
results. A limit of 20 and offset of 20, will get the
second page of 20 results.
Returns:
mixed: Response from the API.
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# The base uri for api requests
query_builder = Configuration.BASE_URI
# Prepare query string for API call
query_builder += "/occurrence/download/dataset/{datasetKey}"
# Process optional template parameters
query_builder = APIHelper.append_url_with_template_parameters(query_builder, {
"datasetKey": options.get('dataset_key', None)
})
# Process optional query parameters
query_builder = APIHelper.append_url_with_query_parameters(query_builder, {
"limit": options.get('limit', None) if options.get('limit', None) is not None else 300,
"offset": options.get('offset', None)
})
# Validate and preprocess url
query_url = APIHelper.clean_url(query_builder)
# Prepare headers
headers = {
"user-agent": "APIMATIC 2.0",
"accept": "application/json"
}
# Prepare and invoke the API call request to fetch the response
response = unirest.get(query_url, headers=headers, params={}, auth=(self.__user, self.__password))
# Error handling using HTTP status codes
if response.code < 200 or response.code > 206: # 200 = HTTP OK
raise APIException("HTTP Response Not OK", response.code, response.body)
return response.body
def get_occurrence_metrics_count(self,
options=dict()):
"""Does a GET request to /occurrence/count.
Returns occurrence counts for a predefined set of dimensions. The
supported dimensions are enumerated in the /occurrence/count/schema
service. An example for the count of georeferenced observations from
Canada:
/occurrence/count?country=CA&isGeoreferenced=true&basisOfRecord=OBSERVA
TION.
Args:
options (dict, optional): Key-value pairs for any of the
parameters to this API Endpoint. All parameters to the
endpoint are supplied through the dictionary with their names
being the key and their desired values being the value. A list
of parameters that can be used are::
basis_of_record -- string -- basisOfRecord
country -- string -- Country
dataset_key -- string -- datasetKey
is_geo_referenced -- bool -- isGeoreferenced
issue -- string -- issue
publishing_country -- string -- publishingCountry
taxon_key -- int -- taxonKey
type_status -- string -- typeStatus
Returns:
int: Response from the API.
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# The base uri for api requests
query_builder = Configuration.BASE_URI
# Prepare query string for API call
query_builder += "/occurrence/count"
# Process optional query parameters
query_builder = APIHelper.append_url_with_query_parameters(query_builder, {
"basisOfRecord": options.get('basis_of_record', None),
"country": options.get('country', None),
"datasetKey": options.get('dataset_key', None),
"isGeoReferenced": options.get('is_geo_referenced', None),
"issue": options.get('issue', None),
"publishingCountry": options.get('publishing_country', None) if options.get('publishing_country', None) is not None else "NZ",
"taxonKey": options.get('taxon_key', None),
"typeStatus": options.get('type_status', None)
})
# Validate and preprocess url
query_url = APIHelper.clean_url(query_builder)
# Prepare headers
headers = {
"user-agent": "APIMATIC 2.0"
}
# Prepare and invoke the API call request to fetch the response
response = unirest.get(query_url, headers=headers)
# Error handling using HTTP status codes
if response.code < 200 or response.code > 206: # 200 = HTTP OK
raise APIException("HTTP Response Not OK", response.code, response.body)
return response.body
def get_occurrence_search_search(self,
options=dict()):
"""Does a GET request to /occurrence/search.
Full search across all occurrences. Results are ordered by relevance.
Args:
options (dict, optional): Key-value pairs for any of the
parameters to this API Endpoint. All parameters to the
endpoint are supplied through the dictionary with their names
being the key and their desired values being the value. A list
of parameters that can be used are::
basis_of_record -- BasisOfRecordEnum -- Basis of record,
as defined in our BasisOfRecord enum
catalog_number -- string -- An identifier of any form
assigned by the source within a physical collection or
digital dataset for the record which may not be
unique, but should be fairly unique in combination
with the institution and collection code.
collection_code -- string -- An identifier of any form
assigned by the source to identify the physical
collection or digital dataset uniquely within the
context of an institution.
continent -- ContinentEnum -- Continent, as defined in the
GBIF Continent enum
country -- string -- The 2-letter country code (as per
ISO-3166-1) of the country in which the occurrence was
recorded.
dataset_key -- string -- The occurrence dataset key (a
uuid)
decimal_latitude -- string -- Latitude in decimals between
-90 and 90 based on WGS 84.. Supports range queries.
decimal_longitude -- string -- Longitude in decimals
between -180 and 180 based on WGS 84.. Supports range
queries.
depth -- string -- Depth in meters relative to altitude.
For example 10 meters below a lake surface with given
altitude. Supports range queries.
elevation -- string -- Elevation (altitude) in meters
above sea level. Supports range queries.
event_date -- string -- Occurrence date in ISO 8601
format: yyyy, yyyy-MM, yyyy-MM-dd, or MM-dd. Supports
range queries.
geometry -- string -- Searches for occurrences inside a
polygon described in Well Known Text (WKT) format.
Only POINT, LINESTRING, LINEARRING and POLYGON are
accepted WKT types. For example, a shape written as
POLYGON ((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))
would be queried as is, i.e.
/occurrence/search?geometry=POLYGON((30.1 10.1, 10 20,
20 40, 40 40, 30.1 10.1)).
has_coordinate -- string -- Limits searches to occurrence
records which contain a value in both latitude and
longitude (i.e. hasCoordinate=true limits to
occurrence records with coordinate values and
hasCoordinate=false limits to occurrence records
without coordinate values).
has_geospatial_issue -- string -- Includes/excludes
occurrence records which contain spatial issues (as
determined in our record interpretation), i.e.
hasGeospatialIssue=true returns only those records
with spatial issues while hasGeospatialIssue=false
includes only records without spatial issues. The
absence of this parameter returns any record with or
without spatial issues.
institution_code -- string -- An identifier of any form
assigned by the source to identify the institution the
record belongs to. Not guaranteed to be unique.
issue -- OccurrenceIssueEnum -- A specific interpretation
issue as defined in our OccurrenceIssue enum
last_interpreted -- string -- This date the record was
last modified in GBIF, in ISO 8601 format: yyyy,
yyyy-MM, yyyy-MM-dd, or MM-dd. Supports range
queries.
limit -- int -- Controls the number of results in the
page. Using too high a value will be overwritten with
the default maximum threshold, depending on the
service. Sensible defaults are used so this may be
omitted.
media_type -- MediaTypeEnum -- The kind of multimedia
associated with an occurrence as defined in our
MediaType enum
month -- string -- The month of the year, starting with 1
for January. Supports range queries.
offset -- int -- Determines the offset for the search
results. A limit of 20 and offset of 20, will get the
second page of 20 results.
publishing_country -- string -- The 2-letter country code
(as per ISO-3166-1) of the owining organization's
country.
recorded_by -- string -- The person who recorded the
occurrence.
record_number -- int -- An identifier given to the record
at the time it was recorded in the field.
scientific_name -- string -- A scientific name from the
GBIF backbone. All included and synonym taxa are
included in the search. Under the hood a call to the
species match service is done first to retrieve a
taxonKey. Only unique scientific names will return
results, homonyms (many monomials) return nothing!
Consider to use the taxonKey parameter instead and the
species match service directly
taxon_key -- string -- A taxon key from the GBIF backbone.
All included and synonym taxa are included in the
search, so a search for aves with taxonKey=212 (i.e.
/occurrence/search?taxonKey=212) will match all birds,
no matter which species.
year -- string -- The 4 digit year. A year of 98 will be
interpreted as AD 98. Supports range queries.
Returns:
mixed: Response from the API.
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# The base uri for api requests
query_builder = Configuration.BASE_URI
# Prepare query string for API call
query_builder += "/occurrence/search"
# Process optional query parameters
query_builder = APIHelper.append_url_with_query_parameters(query_builder, {
"basisOfRecord": options.get('basis_of_record', None).to_string() if options.get('basis_of_record', None) is not None else None,
"catalogNumber": options.get('catalog_number', None),
"collectionCode": options.get('collection_code', None),
"continent": options.get('continent', None).to_string() if options.get('continent', None) is not None else None,
"country": options.get('country', None),
"datasetKey": options.get('dataset_key', None),
"decimalLatitude": options.get('decimal_latitude', None),
"decimalLongitude": options.get('decimal_longitude', None),
"depth": options.get('depth', None),
"elevation": options.get('elevation', None),
"eventDate": options.get('event_date', None),
"geometry": options.get('geometry', None) if options.get('geometry', None) is not None else "POLYGON((160 -60,160 -25,180 -25,180 -60,160 -60))",
"hasCoordinate": options.get('has_coordinate', None),
"hasGeospatialIssue": options.get('has_geospatial_issue', None),
"institutionCode": options.get('institution_code', None),
"issue": options.get('issue', None).to_string() if options.get('issue', None) is not None else None,
"lastInterpreted": options.get('last_interpreted', None),
"limit": options.get('limit', None) if options.get('limit', None) is not None else 300,
"mediaType": options.get('media_type', None).to_string() if options.get('media_type', None) is not None else None,
"month": options.get('month', None),
"offset": options.get('offset', None),
"publishingCountry": options.get('publishing_country', None) if options.get('publishing_country', None) is not None else "NZ",
"recordedBy": options.get('recorded_by', None),
"recordNumber": options.get('record_number', None),
"scientificName": options.get('scientific_name', None),
"taxonKey": options.get('taxon_key', None),
"year": options.get('year', None)
})
# Validate and preprocess url
query_url = APIHelper.clean_url(query_builder)
# Prepare headers
headers = {
"user-agent": "APIMATIC 2.0",
"accept": "application/json"
}
# Prepare and invoke the API call request to fetch the response
response = unirest.get(query_url, headers=headers)
# Error handling using HTTP status codes
if response.code < 200 or response.code > 206: # 200 = HTTP OK
print "RESPONSE\n%s\n%s\n" % (response.code, response.body)
raise APIException("HTTP Response Not OK", response.code, response.body)
return response.body
def get_map_tile(self, options=dict()):
"""Does a GET request to /map/density/tile.
The mapping api is a web map tile service making it trivial to
visualize GBIF content on interactive maps, and overlay content from
other sources. Developers familiar with tile mapping services should
jump straight to the preview functionality The following features are
supported: Map layers available for a country, dataset, taxon
(species, subspecies or higher taxon), publisher User defined
styling by selecting a predefined color palette, or by providing
styling rules Density of content is clustered to a user defined
cluster size (regardless of zoom level) The ability to customise
content shown by the basis of record (E.g. Specimens, Observations,
Fossils etc) For certain basis of record types, the time period
may be customised by decade; e.g. map the observations of a species
since 1970 This service is intended for use with commonly used
clients such as the google maps api, leaflet JS library or the modest
maps JS library. These libraries allow the GBIF layers to be
visualized with other content, such as those coming from web map
service (WMS) providers. It should be noted that the mapping api is
not a WMS service, nor does it support WFS capabilities. The examples
on this page use the leaflet library.
Args:
options (dict, optional): Key-value pairs for any of the
parameters to this API Endpoint. All parameters to the
endpoint are supplied through the dictionary with their names
being the key and their desired values being the value. A list
of parameters that can be used are::
key -- string -- The appropriate key for the chosen type
(a taxon key, dataset/publisher uuid or 2 letter ISO
country code)
mtype -- string -- A value of TAXON, DATASET, COUNTRY or
PUBLISHER
x -- string -- TODO: type description here. Example: 1
y -- string -- TODO: type description here. Example: 1
z -- string -- TODO: type description here. Example: 1
colors -- string -- Provides a user defined set of rules
for coloring the layer. See styling a layer
hue -- double -- Allows selection of a hue value between
0.0 and 1.0 when saturation is set to true. See
styling a layer
layer -- list of string -- (multivalued) Declares the
layers to be combined by the server for this tile. See
Customizing layer content
palette -- PaletteEnum -- Selects a predefined color
palette. See styling a layer
resolution -- int -- The number of pixels to which density
is aggregated. Valid values are 1, 2, 4, 8, and 16.
saturation -- bool -- Allows selection of a hue value
between 0.0 and 1.0 when saturation is set to true.
See styling a layer
Returns:
binary: Response from the API.
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# The base uri for api requests
query_builder = Configuration.BASE_URI
# Prepare query string for API call
query_builder += "/map/density/tile"
# Process optional query parameters
query_builder = APIHelper.append_url_with_query_parameters(
query_builder,
{
"key": options.get("key", None),
"type": options.get("mtype", None),
"x": options.get("x", None),
"y": options.get("y", None),
"z": options.get("z", None),
"colors": options.get("colors", None),
"hue": options.get("hue", None) if options.get("hue", None) is not None else 1.0,
"layer": options.get("layer", None),
"palette": options.get("palette", None).to_string()
if options.get("palette", None) is not None
else None,
"resolution": options.get("resolution", None) if options.get("resolution", None) is not None else 8,
"saturation": options.get("saturation", None) if options.get("saturation", None) is not None else True,
},
)
# Validate and preprocess url
query_url = APIHelper.clean_url(query_builder)
# Prepare headers
headers = {"user-agent": "APIMATIC 2.0"}
# Prepare and invoke the API call request to fetch the response
response = unirest.get(query_url, headers=headers)
# Error handling using HTTP status codes
if response.code < 200 or response.code > 206: # 200 = HTTP OK
raise APIException("HTTP Response Not OK", response.code, response.body)
return response.body
def get_occurrence_inventories_list_count_by_dataset(self,
options=dict()):
"""Does a GET request to /occurrence/counts/datasets.
Lists occurrence counts for datasets that cover a given taxon or
country.
Args:
options (dict, optional): Key-value pairs for any of the
parameters to this API Endpoint. All parameters to the
endpoint are supplied through the dictionary with their names
being the key and their desired values being the value. A list
of parameters that can be used are::
country -- string -- The 2-letter country code (as per
ISO-3166-1) of the country in which the occurrence was
recorded.
taxon_key -- int -- A taxon key from the GBIF backbone.
All included and synonym taxa are included in the
search, so a search for aves with taxonKey=212 (i.e.
/occurrence/search?taxonKey=212) will match all birds,
no matter which species.
Returns:
mixed: Response from the API.
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# The base uri for api requests
query_builder = Configuration.BASE_URI
# Prepare query string for API call
query_builder += "/occurrence/counts/datasets"
# Process optional query parameters
query_builder = APIHelper.append_url_with_query_parameters(query_builder, {
"country": options.get('country', None) if options.get('country', None) is not None else "NZ",
"taxonKey": options.get('taxon_key', None)
})
# Validate and preprocess url
query_url = APIHelper.clean_url(query_builder)
# Prepare headers
headers = {
"user-agent": "APIMATIC 2.0",
"accept": "application/json"
}
# Prepare and invoke the API call request to fetch the response
response = unirest.get(query_url, headers=headers)
# Error handling using HTTP status codes
if response.code < 200 or response.code > 206: # 200 = HTTP OK
raise APIException("HTTP Response Not OK", response.code, response.body)
return response.body