def get_observation_fields(user_agent: str = None, **kwargs) -> ListResponse:
"""Search observation fields. Observation fields are basically typed data fields that
users can attach to observation.
**API reference:** https://www.inaturalist.org/pages/api+reference#get-observation_fields
Example:
>>> get_observation_fields(q='number of individuals')
>>> # Show just observation field IDs and names
>>> from pprint import pprint
>>> pprint({r['id']: r['name'] for r in response})
.. admonition:: Example Response
:class: toggle
.. literalinclude:: ../sample_data/get_observation_fields_page1.json
:language: javascript
Returns:
Observation fields as a list of dicts
"""
kwargs = check_deprecated_params(**kwargs)
response = get(
"{base_url}/observation_fields.json".format(base_url=INAT_BASE_URL),
params=kwargs,
user_agent=user_agent,
)
return response.json()
def get_observations(response_format="json",
user_agent: str = None,
**params) -> Union[Dict, str]:
"""Get observation data, optionally in an alternative format. Return type will be
``dict`` for the ``json`` response format, and ``str`` for all others. Also see
:py:func:`.get_geojson_observations` for GeoJSON format (not included here because it wraps
a separate API endpoint).
For API parameters, see: https://www.inaturalist.org/pages/api+reference#get-observations
Example::
get_observations(id=45414404, format="dwc")
"""
if response_format == "geojson":
raise ValueError(
"For geojson format, use pyinaturalist.node_api.get_geojson_observations"
)
if response_format not in OBSERVATION_FORMATS:
raise ValueError("Invalid response format")
response = get(
urljoin(INAT_BASE_URL, "observations.{}".format(response_format)),
params=params,
user_agent=user_agent,
)
return response.json() if response_format == "json" else response.text
def make_inaturalist_api_get_call(endpoint: str,
**kwargs) -> requests.Response:
"""Make an API call to iNaturalist.
Args:
endpoint: The name of an endpoint not including the base URL e.g. 'observations'
kwargs: Arguments for :py:func:`.api_requests.request`
"""
return get(urljoin(INAT_NODE_API_BASE_URL, endpoint), **kwargs)
def make_inaturalist_api_get_call(endpoint: str,
params: Dict,
user_agent: str = None,
**kwargs) -> requests.Response:
"""Make an API call to iNaturalist.
Args:
endpoint: The name of an endpoint not including the base URL e.g. 'observations'
kwargs: Arguments for :py:func:`requests.request`
"""
response = get(urljoin(INAT_NODE_API_BASE_URL, endpoint),
params=params,
user_agent=user_agent,
**kwargs)
return response
def get_observation_fields(search_query: str = "",
page: int = 1,
user_agent: str = None) -> List[Dict[str, Any]]:
"""
Search the (globally available) observation
:param search_query:
:param page:
:param user_agent: a user-agent string that will be passed to iNaturalist.
:return:
"""
payload = {
"q": search_query,
"page": page
} # type: Dict[str, Union[int, str]]
response = get(
"{base_url}/observation_fields.json".format(base_url=INAT_BASE_URL),
params=payload,
user_agent=user_agent,
)
return response.json()
def get_observations(user_agent: str = None, **kwargs) -> Union[List, str]:
"""Get observation data, optionally in an alternative format. Also see
:py:func:`.get_geojson_observations` for GeoJSON format (not included here because it wraps
a separate API endpoint).
**API reference:** https://www.inaturalist.org/pages/api+reference#get-observations
Example:
>>> get_observations(id=45414404, format="atom")
.. admonition:: Example Response (atom)
:class: toggle
.. literalinclude:: ../sample_data/get_observations.atom
:language: xml
.. admonition:: Example Response (csv)
:class: toggle
.. literalinclude:: ../sample_data/get_observations.csv
.. admonition:: Example Response (dwc)
:class: toggle
.. literalinclude:: ../sample_data/get_observations.dwc
:language: xml
.. admonition:: Example Response (json)
:class: toggle
.. literalinclude:: ../sample_data/get_observations.json
:language: json
.. admonition:: Example Response (kml)
:class: toggle
.. literalinclude:: ../sample_data/get_observations.kml
:language: xml
.. admonition:: Example Response (widget)
:class: toggle
.. literalinclude:: ../sample_data/get_observations.js
:language: javascript
Returns:
Return type will be ``dict`` for the ``json`` response format, and ``str`` for all
others.
"""
response_format = kwargs.pop("response_format", "json")
if response_format == "geojson":
raise ValueError("For geojson format, use pyinaturalist.node_api.get_geojson_observations")
if response_format not in OBSERVATION_FORMATS:
raise ValueError("Invalid response format")
validate_multiple_choice_param(kwargs, "order_by", REST_OBS_ORDER_BY_PROPERTIES)
response = get(
urljoin(INAT_BASE_URL, "observations.{}".format(response_format)),
params=kwargs,
user_agent=user_agent,
)
if response_format == "json":
return convert_lat_long_to_float(response.json())
else:
return response.text