Places

Summary

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(**params)

Search for places near a given location

paginate_autocomplete(**params)

Attempt to get as many results as possible from the places autocomplete endpoint.

Module Contents

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 (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

Example

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

Example Response

{
    'total_results': 2,
    'page': 1,
    'per_page': 2,
    'results': [
        {
            'ancestor_place_ids': [97393, 6803, 8479, 40475, 89191],
            'bounding_box_geojson': {
                'coordinates': [
                    [
                        [172.22944733271785, -43.32610616632186],
                        [172.22944733271785, -43.32459953345999],
                        [172.2351855995691, -43.32459953345999],
                        [172.2351855995691, -43.32610616632186],
                        [172.22944733271785, -43.32610616632186],
                    ]
                ],
                'type': 'Polygon',
            },
            'bbox_area': 8.64546140806803e-06,
            'admin_level': None,
            'place_type': 100,
            'name': 'Conservation Area Riversdale',
            'location': [-43.3254578926, 172.2325124165],
            'id': 89191,
            'display_name': 'Conservation Area Riversdale, CA, NZ',
            'slug': 'conservation-area-riversdale',
            'geometry_geojson': {
                'coordinates': 'TRUNCATED',
                'type': 'MultiPolygon',
            },
        },
        {
            'ancestor_place_ids': None,
            'bounding_box_geojson': {
                'coordinates': [
                    [
                        [176.0643786192, -41.1114421991],
                        [176.0643786192, -41.0804995501],
                        [176.0837817192, -41.0804995501],
                        [176.0837817192, -41.1114421991],
                        [176.0643786192, -41.1114421991],
                    ]
                ],
                'type': 'Polygon',
            },
            'bbox_area': 0.0006003833128119,
            'admin_level': None,
            'place_type': None,
            'name': 'Riversdale Beach',
            'location': [-41.0959708746, 176.0740801692],
            'id': 67591,
            'display_name': 'Riversdale Beach',
            'uuid': 'c5bca3b0-d9f2-44c3-bdb1-1189734a30a4',
            'slug': 'riversdale-beach',
            'geometry_geojson': {
                'coordinates': 'TRUNCATED',
                'type': 'MultiPolygon',
            },
        },
    ],
}
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(**params)

Search for places near a given location

Notes

Parameters

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
...

Example Response

{
    'total_results': 2,
    'page': 1,
    'per_page': 2,
    'results': {
        'standard': [
            {
                'ancestor_place_ids': None,
                'bounding_box_geojson': {
                    'coordinates': [
                        [
                            [0.0132, 5.4508],
                            [0.0132, 83.7083],
                            [-0.0033, 83.7083],
                            [-0.0033, 5.4508],
                            [0.0132, 5.4508],
                        ]
                    ],
                    'type': 'Polygon',
                },
                'bbox_area': 28171.40875125,
                'admin_level': -1,
                'place_type': 29,
                'name': 'North America',
                'location': [56.7732555574, -179.68825],
                'id': 97394,
                'display_name': 'North America',
                'uuid': '22e0b04f-5efe-4383-a167-95079e1d5ce1',
                'slug': 'north-america',
                'geometry_geojson': {'coordinates': 'TRUNCATED', 'type': 'MultiPolygon'},
            }
        ],
        'community': [
            {
                'ancestor_place_ids': [97391, 8858, 11770],
                'bounding_box_geojson': {
                    'coordinates': [
                        [
                            [22.004324, 44.104093],
                            [22.004324, 45.119544],
                            [23.481443, 45.119544],
                            [23.481443, 44.104093],
                            [22.004324, 44.104093],
                        ]
                    ],
                    'type': 'Polygon',
                },
                'bbox_area': 1.49994196566895,
                'admin_level': None,
                'place_type': 8,
                'name': 'Mehedinti',
                'location': [44.6118185, 22.7428835],
                'id': 11770,
                'display_name': 'Mehedinti, RO',
                'uuid': 'efa6a122-7d25-4342-a452-15c7036f6e44',
                'slug': 'mehedinti',
                'geometry_geojson': {'coordinates': 'TRUNCATED', 'type': 'Polygon'},
            }
        ],
    },
}
Return type

Dict[str, Any]

Returns

Response dict containing place records, divided into ‘standard’ and ‘community’ places.

pyinaturalist.v1.places.paginate_autocomplete(**params)

Attempt to get as many results as possible from the places autocomplete endpoint. This is necessary for some problematic places for which there are many matches but not ranked with the desired match(es) first.

This works based on different rankings being returned for order_by=area. No other fields can be sorted on, and direction can’t be specified, but this can at least provide a few additional results beyond the limit of 20.

Return type

Dict[str, Any]