Places

class pyinaturalist.v1.places.PlaceAutocompletePaginator(**kwargs)#

Bases: JsonPaginator, AutocompletePaginator

pyinaturalist.v1.places.get_places_autocomplete(q=None, **params)#

Given a query string, get places with names starting with the search term

Notes

API reference: GET /places/autocomplete
This endpoint accepts a per_page param, up to a max of 20 (default 10)
Pages beyond the first page cannot be retrieved. Use page=all to attempt to retrieve additional results. See paginate_autocomplete() for more info.

Parameters:

q (Optional[str]) – Search query
page (Optional[int]) – Page number of results to return
per_page (Optional[int]) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order (Optional[str]) – Sort order
order_by (Optional[str]) – Field to sort on
count_only (Optional[bool]) – Only return a count of results; alias for per_page=0
reverse (Optional[bool]) – Reverse the order of results; alias for order='descending'
dry_run (Optional[bool]) – Just log the request instead of sending a real request
session (Optional[Session]) – An existing Session object to use instead of creating a new one

Example

>>> response = get_places_autocomplete('Irkutsk')
>>> pprint(response)
[11803] Irkutsk
[41854] Irkutskiy rayon
[166186] Irkutsk Oblast - ADD
[163077] Irkutsk agglomeration

Example Response

{
    'total_results': 4,
    'page': 1,
    'per_page': 4,
    'results': [
        {
            'ancestor_place_ids': [97395, 7161, 11803],
            'bounding_box_geojson': {
                'coordinates': [
                    [
                        [95.5820007324, 51.1188278198],
                        [95.5820007324, 64.2834396362],
                        [119.1222915649, 64.2834396362],
                        [119.1222915649, 51.1188278198],
                        [95.5820007324, 51.1188278198],
                    ]
                ],
                'type': 'Polygon',
            },
            'bbox_area': 309.898790854159,
            'admin_level': 1,
            'place_type': 21,
            'name': 'Irkutsk',
            'location': [57.0842832466, 106.2908666325],
            'id': 11803,
            'display_name': 'Irkutsk, RU',
            'uuid': '5a21bcbc-3975-4d22-81fa-0088543e3247',
            'slug': 'irkutsk',
            'geometry_geojson': {
                'coordinates': 'TRUNCATED',
                'type': 'Polygon',
            },
        },
        {
            'ancestor_place_ids': [97395, 7161, 11803, 41853],
            'bounding_box_geojson': {
                'coordinates': [
                    [
                        [104.175743103, 52.3083381653],
                        [104.175743103, 52.3586273193],
                        [104.2688369751, 52.3586273193],
                        [104.2688369751, 52.3083381653],
                        [104.175743103, 52.3083381653],
                    ]
                ],
                'type': 'Polygon',
            },
            'bbox_area': 0.00468161207394086,
            'admin_level': 2,
            'place_type': 9,
            'name': 'Irkutsk',
            'location': [52.3330788792, 104.2213639696],
            'id': 41853,
            'display_name': 'Irkutsk, IK, RU',
            'uuid': 'ff9b00cd-491d-4414-a7a6-1d25bc16687b',
            'slug': 'irkutsk-irkutsk-ru',
            'geometry_geojson': {
                'coordinates': 'TRUNCATED',
                'type': 'MultiPolygon',
            },
        },
        {
            'ancestor_place_ids': [97395, 7161, 11803, 41854],
            'bounding_box_geojson': {
                'coordinates': [
                    [
                        [103.3993835449, 51.8282775879],
                        [103.3993835449, 52.7414131165],
                        [105.9679870605, 52.7414131165],
                        [105.9679870605, 51.8282775879],
                        [103.3993835449, 51.8282775879],
                    ]
                ],
                'type': 'Polygon',
            },
            'bbox_area': 2.34548312891261,
            'admin_level': 2,
            'place_type': 102,
            'name': 'Irkutskiy rayon',
            'location': [52.2449129844, 104.5715345329],
            'id': 41854,
            'display_name': 'Irkutskiy rayon, IK, RU',
            'uuid': '23f656ae-4830-4934-b0e8-0fdc966565d1',
            'slug': 'irkutskiy-rayon',
            'geometry_geojson': {
                'coordinates': 'TRUNCATED',
                'type': 'Polygon',
            },
        },
        {
            'ancestor_place_ids': [97395, 7161, 163077],
            'bounding_box_geojson': {
                'coordinates': [
                    [
                        [103.1875974, 51.6715918],
                        [103.1875974, 53.0498458],
                        [106.1725331, 53.0498458],
                        [106.1725331, 51.6715918],
                        [103.1875974, 51.6715918],
                    ]
                ],
                'type': 'Polygon',
            },
            'bbox_area': 4.1139995682678,
            'admin_level': None,
            'place_type': 1013,
            'name': 'Irkutsk agglomeration',
            'location': [52.2598446202, 104.6684418399],
            'id': 163077,
            'display_name': 'Irkutsk agglomeration, RU',
            'uuid': '553871d4-762e-4306-a48a-c4c5a3ac18b7',
            'slug': 'irkutsk-agglomeration',
            'geometry_geojson': {
                'coordinates': 'TRUNCATED',
                'type': 'Polygon',
            },
        },
    ],
}

Return type:: Dict[str, Any]
Returns:: Response dict containing place records

pyinaturalist.v1.places.get_places_by_id(place_id, **params)#

Get one or more places by ID

Notes

API reference: GET /places/{id}

Example

>>> response = get_places_by_id([67591, 89191])
>>> pprint(response)
[89191] Conservation Area Riversdale
[67591] Riversdale Beach

Parameters:: place_id (Union[int, Iterable[int]]) – Get a place with this ID. Multiple values are allowed.
Return type:: Dict[str, Any]
Returns:: Response dict containing place records

pyinaturalist.v1.places.get_places_nearby(nelat, nelng, swlat, swlng, **params)#

Search for places near a given location

Notes

API reference: GET /places/nearby

Parameters:

nelat (Optional[float]) – NE latitude of bounding box
nelng (Optional[float]) – NE longitude of bounding box
swlat (Optional[float]) – SW latitude of bounding box
swlng (Optional[float]) – SW longitude of bounding box
name (Optional[str]) – Name must match this value
dry_run (Optional[bool]) – Just log the request instead of sending a real request
session (Optional[Session]) –
An existing Session object to use instead of creating a new one

Example

>>> bounding_box = (150.0, -50.0, -149.999, -49.999)
>>> response = get_places_nearby(*bounding_box)

Response is split into standard (curated) places and community (non-curated) places:

>>> print(len(response['results']['standard']))
10
>>> print(len(response['results']['community']))
10

Show basic info for all places in response:

>>> pprint(response)
[97394] North America
[97395] Asia
[97393] Oceania
...

Return type:: Dict[str, Any]
Returns:: Response dict containing place records, divided into ‘standard’ and ‘community’ places.

Places#

Summary#

Module Contents#

`get_places_autocomplete`([q])	Given a query string, get places with names starting with the search term
`get_places_by_id`(place_id, **params)	Get one or more places by ID
`get_places_nearby`(nelat, nelng, swlat, ...)	Search for places near a given location