def get_taxonomy_groups(token, ordering='ebird', locale='en'):
"""Get the names of the groups of species used in the taxonomy.
The maps to the end point in the eBird API 2.0,
https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#aa9804aa-dbf9-4a53-bbf4-48e214e4677a
NOTE: Not all the locales supported by the eBird site or apps
are available in the API. The following locales are not
supported, (language, locale code):
Croatian, hr
Croatian, hr
Faroese, fo
Finnish, fi
Haitian, ht_HT
Hungarian, hu
Indonesian, id
Italian, it
Japanese, ja
Korean, ko
Latvian, lv
Lithuanian, lt
Malayalam, ml
Mongolian, mn
Polish, pl
Slovenian, sl
Swedish, sv
Ukrainian, uk
:param token: the token needed to access the API.
:param ordering: order groups using taxonomic order, 'ebird' or by
likeness, 'merlin'.
:param locale: the language (to use) for the group names.
:return: the list of species groups.
:raises ValueError: if an invalid ordering or locale is given.
:raises URLError if there is an error with the connection to the
eBird site.
:raises HTTPError if the eBird API returns an error.
"""
url = TAXONOMY_GROUPS_URL % clean_ordering(ordering)
params = {
'groupNameLocale': clean_locale(locale),
}
headers = {
'X-eBirdApiToken': token,
}
return call(url, params, headers)
def get_taxonomy(token,
category=None,
locale='en',
version=None,
species=None):
"""Get the full or specific subset of the taxonomy used by eBird.
The maps to the end point in the eBird API 2.0,
https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#952a4310-536d-4ad1-8f3e-77cfb624d1bc
:param token: the token needed to access the API.
:param category: one or more categories of species to return: 'domestic',
'form', 'hybrid', 'intergrade', 'issf', 'slash', 'species' or 'spuh'.
More than one value can be given in a comma-separated string.
:param locale: the language (to use) for the species common names. The
default of 'en' will use species names from the eBird/Clements checklist.
This can be any locale for which eBird has translations available. For a
complete list see, http://help.ebird.org/customer/portal/articles/1596582.
:param version: the version number of the taxonomy to return,
see get_taxonomy_versions()
:param species: a comma-separate string or list containing scientific
names or 6-letter species codes.
:return: the list of entries matching the category.
:raises ValueError: if an invalid category or locale is given.
:raises ValueError: if both a category and species are used. In this case
the eBird API ignore the species and returns only results for the category.
:raises URLError if there is an error with the connection to the
eBird site.
:raises HTTPError if the eBird API returns an error.
"""
params = {'sppLocale': clean_locale(locale), 'fmt': 'json'}
if category is not None:
params['cat'] = ','.join(clean_categories(category))
if version is not None:
params['version'] = version
if species is not None:
params['species'] = ','.join(clean_codes(species))
headers = {
'X-eBirdApiToken': token,
}
return call(TAXONOMY_URL, params, headers)
def __init__(self, api_key, locale):
self.api_key = api_key
self.locale = clean_locale(locale)
self.max_observations = None
self.max_visits = 200
self.max_observers = 100
self.back = 14
self.category = None
self.detail = 'full'
self.dist = 25
self.hotspot = False
self.provisional = True
self.sort = 'date'
def get_nearest_species(token,
species,
lat,
lng,
dist=25,
back=14,
max_results=None,
locale='en',
provisional=False,
hotspot=False):
"""Get the nearest, recent, observations of a species.
Get the recent observations (up to 30 days ago) for a species seen at
locations closest to a set of coordinates (latitude, longitude).
IMPORTANT: As of 2019-05-27 the dist parameter does not appear to be
respected and so this call will return records from anywhere the
specified species are reported. Also the English common name for the
species is always returned regardless of which locale is specified.
The maps to the end point in the eBird API 1.1,
https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#6bded97f-9997-477f-ab2f-94f254954ccb
:param token: the token needed to access the API.
:param species: the scientific name of the species.
:param lat: the latitude, which will be rounded to 2 decimal places.
:param lng: the longitude, which will be rounded to 2 decimal places.
:param dist: include all sites within this distance, from 0 to 50km
with a default of 25km.
:param back: the number of days in the past to include. Ranges from
1 to 30 with a default of 14 days.
:param max_results: the maximum number of observations to return from
1 to 1000. The default value is None which means all observations will
be returned.
:param locale: the language (to use) for the species common names. The
default of 'en_US' will use species names from the eBird/Clements checklist.
This can be any locale for which eBird has translations available. For a
complete list see, http://help.ebird.org/customer/portal/articles/1596582.
:param provisional: include records which have not yet been reviewed.
Either True or False, the default is False.
:param hotspot: get only observations from hotspots, in other words
exclude private locations. The default is False so observations will
be returned from all locations.
:return: the list of observations in 'simple' form. See the eBird API
documentation for a description of the fields.
:raises ValueError: if any of the arguments fail the validation checks.
:raises URLError if there is an error with the connection to the
eBird site.
:raises HTTPError if the eBird API returns an error.
"""
url = NEAREST_SPECIES_URL % species
params = {
'lat': clean_lat(lat),
'lng': clean_lng(lng),
'back': clean_back(back),
'dist': clean_dist(dist),
'maxObservations': clean_max_observations(max_results),
'sppLocale': clean_locale(locale),
'includeProvisional': clean_provisional(provisional),
'hotspot': clean_hotspot(hotspot),
}
headers = {
'X-eBirdApiToken': token,
}
return call(url, params, headers)
def get_historic_observations(token,
area,
date,
max_results=None,
locale='en',
provisional=False,
hotspot=False,
detail='simple',
category=None):
"""Get recent observations for a region.
Get all the recent observations (up to 30 days ago) for a region.
The maps to the end point in the eBird API 2.0,
https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#2d8c6ee8-c435-4e91-9f66-6d3eeb09edd2
:param token: the token needed to access the API.
:param area: a country, subnational1, subnational2 or location code
or a list of up to 10 codes. All codes must be same type.
:param date: the date, since Jan 1st 1800.
:param max_results: the maximum number of observations to return from
1 to 10000. The default value is None which means all observations will
be returned.
:param locale: the language (to use) for the species common names. The
default of 'en_US' will use species names from the eBird/Clements checklist.
This can be any locale for which eBird has translations available. For a
complete list see, http://help.ebird.org/customer/portal/articles/1596582.
:param provisional: include records which have not yet been reviewed.
Either True or False, the default is False.
:param hotspot: return records only from hotspots, True or include both
hotspots and private locations, False (the default).
:param detail: return records in 'simple' or 'full' format. See the
eBird API documentation for a description of the fields.
:param category: one or more categories of species to return: 'domestic',
'form', 'hybrid', 'intergrade', 'issf', 'slash', 'species' or 'spuh'.
More than one value can be given in a comma-separated string. The default
value is None and records from all categories will be returned.
:return: the list of observations in simple format.
:raises ValueError: if any of the arguments fail the validation checks.
:raises URLError if there is an error with the connection to the
eBird site.
:raises HTTPError if the eBird API returns an error.
"""
cleaned = clean_areas(area)
url = HISTORIC_OBSERVATIONS_URL % (cleaned[0], date.strftime('%Y/%m/%d'))
params = {
'rank': 'mrec',
'detail': clean_detail(detail),
'sppLocale': clean_locale(locale),
'includeProvisional': clean_provisional(provisional),
'hotspot': clean_hotspot(hotspot),
'maxObservations': clean_max_observations(max_results),
}
if len(cleaned) > 1:
params['r'] = ','.join(cleaned)
if category is not None:
params['cat'] = ','.join(clean_categories(category))
headers = {
'X-eBirdApiToken': token,
}
return call(url, params, headers)
def get_nearby_notable(token,
lat,
lng,
dist=25,
back=14,
max_results=None,
locale='en',
hotspot=False,
detail='simple'):
"""Get the nearby, recent observations of rare species.
Get all the recent observations (up to 30 days ago) for a species seen at
locations in an area centered on a set of coordinates (latitude, longitude)
and optional distance (up to 50km away) which are locally or nationally
rare.
The maps to the end point in the eBird API 2.0,
https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#caa348bb-71f6-471c-b203-9e1643377cbc
:param token: the token needed to access the API.
:param lat: the latitude, which will be rounded to 2 decimal places.
:param lng: the longitude, which will be rounded to 2 decimal places.
:param dist: include all sites within this distance, from 0 to 50km
with a default of 25km.
:param back: the number of days in the past to include. Ranges from
1 to 30 with a default of 14 days.
:param max_results: the maximum number of observations to return from
1 to 10000. The default value is None which means all observations will
be returned.
:param locale: the language (to use) for the species common names. The
default of 'en_US' will use species names from the eBird/Clements checklist.
This can be any locale for which eBird has translations available. For a
complete list see, http://help.ebird.org/customer/portal/articles/1596582.
:param hotspot: get only observations from hotspots, in other words
exclude private locations. The default is False so observations will be
returned from all locations.
:param detail: return records in 'simple' or 'full' format. See the eBird
API documentation for a description of the fields.
:return: the list of observations.
:raises ValueError: if any of the arguments fail the validation checks.
:raises URLError if there is an error with the connection to the
eBird site.
:raises HTTPError if the eBird API returns an error.
"""
params = {
'lat': clean_lat(lat),
'lng': clean_lng(lng),
'dist': clean_dist(dist),
'back': clean_back(back),
'maxObservations': clean_max_observations(max_results),
'sppLocale': clean_locale(locale),
'hotspot': clean_hotspot(hotspot),
'detail': clean_detail(detail),
}
headers = {
'X-eBirdApiToken': token,
}
return call(NEARBY_NOTABLE_URL, params, headers)
def get_nearby_species(token,
species,
lat,
lng,
dist=25,
back=14,
max_results=None,
locale='en',
provisional=False,
hotspot=False,
category=None):
"""Get most recent observation of a species nearby.
Get the most recent observation (up to 30 days ago) for a species seen at
any locations in an area centered on a set of coordinates (latitude,
longitude) and optional distance (up to 50km away).
The maps to the end point in the eBird API 1.1,
https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#20fb2c3b-ee7f-49ae-a912-9c3f16a40397
:param token: the token needed to access the API.
:param species: the scientific name of the species.
:param lat: the latitude, which will be rounded to 2 decimal places.
:param lng: the longitude, which will be rounded to 2 decimal places.
:param dist: include all sites within this distance, from 0 to 50km
with a default of 25km.
:param back: the number of days in the past to include. Ranges from
1 to 30 with a default of 14 days.
:param max_results: the maximum number of observations to return from
1 to 10000. The default value is None which means all observations will
be returned.
:param locale: the language (to use) for the species common names. The
default of 'en_US' will use species names from the eBird/Clements checklist.
This can be any locale for which eBird has translations available. For a
complete list see, http://help.ebird.org/customer/portal/articles/1596582.
:param provisional: include records which have not yet been reviewed.
Either True or False, the default is False.
:param hotspot: get only observations from hotspots, in other words exclude
private locations. The default is False so observations will be returned from
all locations.
:param category: one or more categories of species to return: 'domestic',
'form', 'hybrid', 'intergrade', 'issf', 'slash', 'species' or 'spuh'.
More than one value can be given in a comma-separated string. The default
value is None and records from all categories will be returned. It's not
clear what the purpose of this parameter is given the species is being
specified. It is not documented on the eBird API page but it is supported
by the code.
:return: the list of observations in 'simple' form. See the eBird API
documentation for a description of the fields.
:raises ValueError: if any of the arguments fail the validation checks.
:raises URLError if there is an error with the connection to the
eBird site.
:raises HTTPError if the eBird API returns an error.
"""
url = NEARBY_SPECIES_URL % species
params = {
'lat': clean_lat(lat),
'lng': clean_lng(lng),
'dist': clean_dist(dist),
'back': clean_back(back),
'maxObservations': clean_max_observations(max_results),
'sppLocale': clean_locale(locale),
'includeProvisional': clean_provisional(provisional),
'hotspot': clean_hotspot(hotspot),
}
if category is not None:
params['cat'] = ','.join(clean_categories(category))
headers = {
'X-eBirdApiToken': token,
}
return call(url, params, headers)
def get_nearby_observations(token,
lat,
lng,
dist=25,
back=14,
max_results=None,
locale='en',
provisional=False,
hotspot=False,
category=None,
sort='date'):
"""Get nearby recent observations of each species.
Get recent observations (up to 30 days ago) of each species from all
locations in an area centered on a set of coordinates (latitude,
longitude) and optional distance (up to 50km away, with a default
distance of 25km).
NOTE: Only the most recent record of each species is returned.
The maps to the end point in the eBird API 1.1,
https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#62b5ffb3-006e-4e8a-8e50-21d90d036edc
:param token: the token needed to access the API.
:param lat: the latitude, which will be rounded to 2 decimal places.
:param lng: the longitude, which will be rounded to 2 decimal places.
:param dist: include all sites within this distance, from 0 to 50km
with a default of 25km.
:param back: the number of days in the past to include. Ranges from
1 to 30 with a default of 14 days.
:param max_results: the maximum number of observations to return from
1 to 10000. The default value is None which means all observations will
be returned.
:param locale: the language (to use) for the species common names. The
default of 'en_US' will use species names from the eBird/Clements checklist.
This can be any locale for which eBird has translations available. For a
complete list see, http://help.ebird.org/customer/portal/articles/1596582.
:param provisional: include records which have not yet been reviewed.
Either True or False, the default is False.
:param hotspot: get only observations from hotspots, in other words
exclude private locations. The default is False so observations will
be returned from all locations.
:param category: one or more categories of species to return: 'domestic',
'form', 'hybrid', 'intergrade', 'issf', 'slash', 'species' or 'spuh'.
More than one value can be given in a comma-separated string. The default
value is None and records from all categories will be returned.
:param sort: return the records sorted by date, 'date' or taxonomy, 'species'.
:return: the list of observations in simple format.
:raises ValueError: if any of the arguments fail the validation checks.
:raises URLError if there is an error with the connection to the
eBird site.
:raises HTTPError if the eBird API returns an error.
"""
params = {
'lat': clean_lat(lat),
'lng': clean_lng(lng),
'dist': clean_dist(dist),
'back': clean_back(back),
'maxObservations': clean_max_observations(max_results),
'sppLocale': clean_locale(locale),
'includeProvisional': clean_provisional(provisional),
'hotspot': clean_hotspot(hotspot),
'sort': clean_sort(sort),
}
if category is not None:
params['cat'] = ','.join(clean_categories(category))
headers = {
'X-eBirdApiToken': token,
}
return call(NEARBY_OBSERVATIONS_URL, params, headers)
def get_species_observations(token,
species,
area,
back=14,
max_results=None,
locale='en',
provisional=False,
hotspot=False,
detail='simple',
category=None):
"""Get recent observations for a given species in a region.
Get all the recent observations (up to 30 days ago) for a species
in a given region.
The maps to the end point in the eBird API 2.0,
https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#755ce9ab-dc27-4cfc-953f-c69fb0f282d9
:param token: the token needed to access the API.
:param species: the scientific name of the species.
:param area: a country, subnational1, subnational2 or location code
or a list of up to 10 codes. All codes must be same type.
:param back: the number of days in the past to include. Ranges from
1 to 30 with a default of 14 days.
:param max_results: the maximum number of observations to return from
1 to 10000. The default value is None which means all observations will
be returned.
:param locale: the language (to use) for the species common names. The
default of 'en' will use species names from the eBird/Clements checklist.
This can be any locale for which eBird has translations available. For a
complete list see, http://help.ebird.org/customer/portal/articles/1596582.
:param provisional: include records which have not yet been reviewed.
Either True or False, the default is False.
:param hotspot: return records only from hotspots, True or include both
hotspots and private locations, False (the default).
:param detail: return records in 'simple' or 'full' format. See the eBird
API documentation for a description of the fields.
:param category: one or more categories of species to return: 'domestic',
'form', 'hybrid', 'intergrade', 'issf', 'slash', 'species' or 'spuh'.
More than one value can be given in a comma-separated string. The default
value is None and records from all categories will be returned. It's not clear
what the purpose of this parameter is given the species is being specified.
It is not documented on the eBird API page but it is supported by the code.
:return: the list of observations in simple format.
:raises ValueError: if any of the arguments fail the validation checks.
:raises URLError if there is an error with the connection to the
eBird site.
:raises HTTPError if the eBird API returns an error.
"""
cleaned = clean_areas(area)
url = SPECIES_OBSERVATIONS_URL % (cleaned[0], species)
params = {
'back': clean_back(back),
'maxObservations': clean_max_observations(max_results),
'sppLocale': clean_locale(locale),
'includeProvisional': clean_provisional(provisional),
'hotspot': clean_hotspot(hotspot),
'detail': clean_detail(detail),
}
if category is not None:
params['cat'] = ','.join(clean_categories(category))
if len(cleaned) > 1:
params['r'] = ','.join(cleaned)
headers = {
'X-eBirdApiToken': token,
}
return call(url, params, headers)
def get_notable_observations(token,
area,
back=14,
max_results=None,
locale='en',
hotspot=False,
detail='simple'):
"""Get recent observations of a rare species for a region or location
Get all the recent observations (up to 30 days ago) of species classes
as rare (locally or nationally) for a country, subnational1 region,
subnational2 region or location.
The maps to the end point in the eBird API 2.0,
https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#397b9b8c-4ab9-4136-baae-3ffa4e5b26e4
:param token: the token needed to access the API.
:param area: a country, subnational1, subnational2 or location code
or a list of up to 10 codes. All codes must be same type.
:param back: the number of days in the past to include. Ranges from
1 to 30 with a default of 14 days.
:param max_results: the maximum number of observations to return from
1 to 10000. The default value is None which means all observations will
be returned.
:param locale: the language (to use) for the species common names. The
default of 'en' will use species names from the eBird/Clements checklist.
This can be any locale for which eBird has translations available. For a
complete list see, http://help.ebird.org/customer/portal/articles/1596582.
:param hotspot: return records only from hotspots, True or include both
hotspots and private locations, False (the default).
:param detail: return records in 'simple' or 'full' format. See the eBird
API documentation for a description of the fields.
:return: the list of observations.
:raises ValueError: if any of the arguments fail the validation checks.
:raises URLError if there is an error with the connection to the
eBird site.
:raises HTTPError if the eBird API returns an error.
"""
cleaned = clean_areas(area)
url = NOTABLE_OBSERVATIONS_URL % cleaned[0]
params = {
'back': clean_back(back),
'maxObservations': clean_max_observations(max_results),
'sppLocale': clean_locale(locale),
'hotspot': clean_hotspot(hotspot),
'detail': clean_detail(detail),
}
if len(cleaned) > 1:
params['r'] = ','.join(cleaned)
headers = {
'X-eBirdApiToken': token,
}
return call(url, params, headers)