pyinaturalist.response_format module¶
Helper functions for formatting API responses
-
pyinaturalist.response_format.
as_geojson_feature
(result, properties=None)[source]¶ Convert an individual response item to a geojson Feature object, optionally with specific response properties included.
- Parameters
result (
Dict
[str
,Any
]) – A single response itemproperties (
Optional
[List
[str
]]) – Whitelist of specific properties to include
- Return type
Dict
[str
,Any
]
-
pyinaturalist.response_format.
as_geojson_feature_collection
(results, properties=None)[source]¶ Convert results from an API response into a geojson FeatureCollection object. This is currently only used for observations, but could be used for any other responses with geospatial info.
- Parameters
results (
Iterable
[Dict
[str
,Any
]]) – List of results from API responseproperties (
Optional
[List
[str
]]) – Whitelist of specific properties to include
- Return type
Dict
[str
,Any
]
-
pyinaturalist.response_format.
convert_all_coordinates
(results)[source]¶ Convert coordinate pairs in response items from strings to floats, if valid
- Parameters
results (
List
[Dict
[str
,Any
]]) – Results from API response; expects coordinates in either ‘location’ key or ‘latitude’ and ‘longitude’ keys- Return type
List
[Dict
[str
,Any
]]
-
pyinaturalist.response_format.
convert_all_place_coordinates
(response)[source]¶ Convert locations for both standard and community-contributed places to floats
- Return type
Dict
[str
,Any
]- Parameters
response (Dict[str, Any]) –
-
pyinaturalist.response_format.
convert_all_timestamps
(results)[source]¶ Replace all date/time info with datetime objects, where possible
- Return type
List
[Dict
[str
,Any
]]- Parameters
results (List[Dict[str, Any]]) –
-
pyinaturalist.response_format.
convert_generic_timestamps
(result)[source]¶ Replace generic created/updated info that’s returned by multiple endpoints. Note: Compared to observation timestamps, these are generally more reliable. These seem to be consistently in ISO 8601 format.
- Return type
Dict
[str
,Any
]- Parameters
result (Dict[str, Any]) –
-
pyinaturalist.response_format.
convert_lat_long
(result)[source]¶ Convert a coordinate pair in a response item from strings to floats, if valid
- Return type
Dict
[str
,Any
]- Parameters
result (Dict[str, Any]) –
-
pyinaturalist.response_format.
convert_location
(result)[source]¶ Convert a coordinate pairs in a response item from strings to floats, if valid
- Parameters
result (Dict[str, Any]) –
-
pyinaturalist.response_format.
convert_observation_timestamps
(result)[source]¶ Replace observation date/time info with datetime objects
- Return type
Dict
[str
,Any
]- Parameters
result (Dict[str, Any]) –
-
pyinaturalist.response_format.
convert_offset
(datetime_obj, tz_offset=None, tz_name=None)[source]¶ Use timezone offset info to replace a datetime’s tzinfo
- Return type
Optional
[datetime
]- Parameters
datetime_obj (Optional[datetime.datetime]) –
tz_offset (str) –
tz_name (str) –
-
pyinaturalist.response_format.
flatten_nested_params
(observation)[source]¶ - Extract some nested observation properties to include at the top level;
this makes it easier to specify these as properties for
as_as_geojson_feature_collection()
.
- Parameters
observation (
Dict
[str
,Any
]) – A single observation result- Return type
Dict
[str
,Any
]
-
pyinaturalist.response_format.
format_histogram
(response)[source]¶ Format a response containing time series data into a single
{date: value}
dict- Return type
Dict
[Union
[date
,datetime
,int
],int
]- Parameters
response (Dict[str, Any]) –
-
pyinaturalist.response_format.
format_observation
(observation)[source]¶ Make a condensed summary from basic observation details: what, who, when, where
- Return type
str
- Parameters
observation (Dict[str, Any]) –
-
pyinaturalist.response_format.
format_taxon
(taxon, align=False)[source]¶ Format a taxon result into a single string containing taxon ID, rank, and name (including common name, if available).
- Return type
str
- Parameters
taxon (Dict[str, Any]) –
align (bool) –
-
pyinaturalist.response_format.
parse_offset
(tz_offset, tz_name=None)[source]¶ Convert a timezone offset string to a tzoffset object, accounting for some common variations in format
Examples
>>> parse_offset('GMT-08:00', 'PST') tzoffset('PST', -28800) >>> parse_offset('-06:00') tzoffset(None, -21600) >>> parse_offset('+05:30') tzoffset(None, 19800) >>> parse_offset('0530') tzoffset(None, 19800)
- Return type
tzoffset
- Parameters
tz_offset (str) –
tz_name (str) –