Projects¶

Summary¶

Classes

Functions

`add_project_observation`(project_id, ...[, ...])	Add an observation to a project
`add_project_users`(project_id, user_ids, **params)	Add users to project observation rules
`delete_project_observation`(project_id, ...)	Remove an observation from a project
`delete_project_users`(project_id, user_ids, ...)	Remove users from project observation rules
`get_projects`(**params)	Search projects
`get_projects_by_id`(project_id[, ...])	Get one or more projects by ID
`update_project`(project_id, **params)	Update a project

Module Contents¶

pyinaturalist.v1.projects.add_project_observation(project_id, observation_id, access_token=None, **params)¶

Add an observation to a project

Notes

Requires authentication
API reference: POST projects/{id}/add
API reference: POST /project_observations

Parameters:

access_token (str) – An access token required for user authentication, as returned by get_access_token()
project_id (int) – ID of project to add onto
observation_id (int) – ID of observation to add
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

>>> add_project_observation(24237, 1234, access_token)

Return type:: Dict[str, Any]
Returns:: Information about the added project observation

pyinaturalist.v1.projects.add_project_users(project_id, user_ids, **params)¶

Add users to project observation rules

Notes

Requires authentication
This only affects observation rules, not project membership

Parameters:

project_id (Union[int, str]) – Either numeric project ID or URL slug
user_ids (Union[int, Iterable[int]]) – One or more user IDs to add. Only accepts numeric IDs.

Return type:

Dict[str, Any]

Returns:

The updated project record

pyinaturalist.v1.projects.delete_project_observation(project_id, observation_id, access_token=None, **params)¶

Remove an observation from a project

Notes

Requires authentication
API reference: DELETE /projects/{id}/remove
API reference: DELETE /project_observations

Parameters:

access_token (str) – An access token required for user authentication, as returned by get_access_token()
project_id (int) – ID of project to add onto
observation_id (int) – ID of observation to add
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

>>> delete_project_observation(24237, 1234, access_token=access_token)

pyinaturalist.v1.projects.delete_project_users(project_id, user_ids, **params)¶

Remove users from project observation rules

Notes

Requires authentication
This only affects observation rules, not project membership

Parameters:

project_id (Union[int, str]) – Either numeric project ID or URL slug
user_ids (Union[int, Iterable[int]]) – One or more user IDs to remove. Only accepts numeric IDs.

Return type:

Dict[str, Any]

Returns:

The updated project record

pyinaturalist.v1.projects.get_projects(**params)¶

Search projects

Notes

API reference: GET /projects

Parameters:

q (Optional[str]) – Project name must begin with this value
id (Union[int, Iterable[int], None]) – Must have this ID
not_id (Union[int, Iterable[int], None]) – Must not have this ID
lat (Optional[float]) – Must be within a radius kilometer circle around this lat/lng
lng (Optional[float]) – Must be within a radius kilometer circle around this lat/lng
radius (int) – Distance from center ((lat, lng)) to search, in kilometers. Defaults to 500km.
featured (Optional[bool]) – Must be marked featured for the relevant site
noteworthy (Optional[bool]) – Must be marked noteworthy for the relevant site
place_id (Union[int, Iterable[int], None]) – Must be in the place with this ID
site_id (Optional[int]) – Site ID that applies to featured and noteworthy. Defaults to the site of the authenticated user, or to the main iNaturalist site
rule_details (Optional[bool]) – Return more information about project rules, for example return a full taxon object instead of simply an ID
type (Union[str, Iterable[str], None]) – Projects must be of this type
member_id (Optional[int]) – Project must have member with this user ID
has_params (Optional[bool]) – Must have search parameter requirements
has_posts (Optional[bool]) – Must have posts
order_by (Optional[str]) – Sort order. distance only applies if lat and lng are specified. featured only applies if featured or noteworthy are true.
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 – 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

Search for projects about invasive species within 400km of Vancouver, BC:

>>> response = get_projects(
>>>     q='invasive',
>>>     lat=49.27,
>>>     lng=-123.08,
>>>     radius=400,
>>>     order_by='distance',
>>> )

Show basic info for projects in response:

>>> pprint(response)
[8291    ] PNW Invasive Plant EDDR
[19200   ] King County (WA) Noxious and Invasive Weeds
[102925  ] Keechelus/Kachess Invasive Plants
...

Example Response

from datetime import datetime

from dateutil.tz import tzutc

{
    'total_results': 5,
    'page': 1,
    'per_page': 5,
    'results': [
        {
            'icon': 'https://www.inaturalist.org/attachment_defaults/general/span2.png',
            'flags': [],
            'description': 'To identify plants to report to the Pacific Northwest Invasive Plant Council',
            'created_at': datetime(2016, 7, 20, 23, 0, 5, tzinfo=tzutc()),
            'title': 'PNW Invasive Plant EDDR',
            'banner_color': '#4551b7',
            'project_observation_rules': [
                {
                    'operand_id': 90550,
                    'id': 616862,
                    'operand_type': 'Project',
                    'operator': 'in_project?',
                }
            ],
            'site_features': [
                {'noteworthy': True, 'site_id': 1, 'featured_at': '2021-03-16T16:41:32.477Z'}
            ],
            'project_observation_fields': [],
            'updated_at': datetime(2020, 12, 21, 18, 11, 26, tzinfo=tzutc()),
            'terms': None,
            'prefers_user_trust': False,
            'id': 8291,
            'slug': 'pnw-invasive-plant-eddr',
            'place_id': None,
            'icon_file_name': None,
            'project_type': '',
            'user_ids': [
                19344,
                233188,
                300949,
                433100,
                450943,
                484450,
                550199,
                705929,
                800947,
                1257963,
                1299400,
                1325105,
                1447496,
                1559261,
                1572257,
                1574151,
                1781965,
                1935125,
                1973277,
                2025991,
                2026024,
                2069171,
                2162268,
                2269792,
                2354291,
                2410332,
                2453818,
                2499882,
                2581775,
                2714743,
                3145074,
                3272396,
                3387092,
                3908364,
            ],
            'header_image_file_name': None,
            'search_parameters': [
                {
                    'field': 'quality_grade',
                    'value': ['research', 'needs_id'],
                    'value_keyword': ['research', 'needs_id'],
                }
            ],
            'rule_preferences': [{'field': 'quality_grade', 'value': 'research,needs_id'}],
            'user_id': 233188,
            'hide_title': False,
            'location': [48.777404, -122.306929],
            'header_image_contain': False,
            'admins': [
                {
                    'role': 'manager',
                    'user_id': 233188,
                    'project_id': 8291,
                    'id': 142985,
                    'user': {
                        'id': 233188,
                        'login': 'borsope',
                        'spam': False,
                        'suspended': False,
                        'created_at': '2016-05-08T14:01:17+00:00',
                        'login_autocomplete': 'borsope',
                        'login_exact': 'borsope',
                        'name': 'Pam Borso',
                        'name_autocomplete': 'Pam Borso',
                        'orcid': None,
                        'icon': None,
                        'observations_count': 3164,
                        'identifications_count': 0,
                        'journal_posts_count': 0,
                        'activity_count': 3164,
                        'species_count': 1346,
                        'universal_search_rank': 3164,
                        'roles': [],
                        'site_id': 1,
                        'icon_url': None,
                    },
                }
            ],
            'header_image_url': None,
            'latitude': 48.777404,
            'longitude': -122.306929,
            'is_umbrella': False,
            'user': {
                'id': 233188,
                'login': 'borsope',
                'spam': False,
                'suspended': False,
                'created_at': '2016-05-08T14:01:17+00:00',
                'login_autocomplete': 'borsope',
                'login_exact': 'borsope',
                'name': 'Pam Borso',
                'name_autocomplete': 'Pam Borso',
                'orcid': None,
                'icon': None,
                'observations_count': 3164,
                'identifications_count': 0,
                'journal_posts_count': 0,
                'activity_count': 3164,
                'species_count': 1346,
                'universal_search_rank': 3164,
                'roles': [],
                'site_id': 1,
                'icon_url': None,
            },
        },
    ],
}

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

pyinaturalist.v1.projects.get_projects_by_id(project_id, rule_details=None, force_refresh=False, **params)¶

Get one or more projects by ID

Notes

API reference: GET /projects/{id}

Example

>>> response = get_projects_by_id([8348, 6432])
>>> pprint(response)
[8348] Tucson High Native and Invasive Species Inventory
[6432] CBWN Invasive Plants

Example Response

from datetime import datetime

from dateutil.tz import tzutc

{
    'total_results': 1,
    'page': 1,
    'per_page': 1,
    'results': [
        {
            'icon': 'https://static.inaturalist.org/projects/8348-icon-span2.JPG?1505526661',
            'flags': [],
            'description': 'The purpose of this project is to document the native and invasive species (including plants, animals and fungus) present on the Tucson High campus. This is an on-going, open project, with the goal of helping students learn the difference between native and non-native species. ',
            'created_at': datetime(2016, 7, 26, 23, 8, 47, tzinfo=tzutc()),
            'title': 'Tucson High Native and Invasive Species Inventory',
            'banner_color': None,
            'project_observation_rules': [],
            'site_features': [],
            'project_observation_fields': [],
            'updated_at': datetime(2017, 9, 16, 1, 51, 1, tzinfo=tzutc()),
            'terms': None,
            'id': 8348,
            'slug': 'tucson-high-native-and-invasive-species-inventory',
            'place_id': 96103,
            'icon_file_name': 'IMG_1263.JPG',
            'project_type': '',
            'user_ids': [84403, 311743],
            'header_image_file_name': None,
            'search_parameters': [
                {
                    'field': 'quality_grade',
                    'value': ['research', 'needs_id'],
                    'value_keyword': ['research', 'needs_id'],
                },
                {'field': 'place_id', 'value_number': [96103], 'value': [96103]},
            ],
            'rule_preferences': [{'field': 'quality_grade', 'value': 'research,needs_id'}],
            'user_id': 84403,
            'hide_title': False,
            'location': [32.2264416406, -110.9617278383],
            'header_image_contain': False,
            'admins': [
                {
                    'role': 'manager',
                    'user_id': 84403,
                    'project_id': 8348,
                    'id': 144092,
                    'user': {
                        'id': 84403,
                        'login': 'ebmartin',
                        'spam': False,
                        'suspended': False,
                        'created_at': '2015-03-20T22:53:09+00:00',
                        'login_autocomplete': 'ebmartin',
                        'login_exact': 'ebmartin',
                        'name': 'Elena Martin',
                        'name_autocomplete': 'Elena Martin',
                        'orcid': None,
                        'icon': 'https://static.inaturalist.org/attachments/users/icons/84403/thumb.jpg?1475546770',
                        'observations_count': 50,
                        'identifications_count': 0,
                        'journal_posts_count': 0,
                        'activity_count': 50,
                        'species_count': 29,
                        'universal_search_rank': 50,
                        'roles': [],
                        'site_id': 1,
                        'icon_url': 'https://static.inaturalist.org/attachments/users/icons/84403/medium.jpg?1475546770',
                    },
                }
            ],
            'header_image_url': None,
            'latitude': 32.2264416406,
            'longitude': -110.9617278383,
            'is_umbrella': False,
            'user': {
                'id': 84403,
                'login': 'ebmartin',
                'spam': False,
                'suspended': False,
                'created_at': '2015-03-20T22:53:09+00:00',
                'login_autocomplete': 'ebmartin',
                'login_exact': 'ebmartin',
                'name': 'Elena Martin',
                'name_autocomplete': 'Elena Martin',
                'orcid': None,
                'icon': 'https://static.inaturalist.org/attachments/users/icons/84403/thumb.jpg?1475546770',
                'observations_count': 50,
                'identifications_count': 0,
                'journal_posts_count': 0,
                'activity_count': 50,
                'species_count': 29,
                'universal_search_rank': 50,
                'roles': [],
                'site_id': 1,
                'icon_url': 'https://static.inaturalist.org/attachments/users/icons/84403/medium.jpg?1475546770',
            },
        }
    ],
}

Parameters:

project_id (Union[int, Iterable[int], str, Iterable[str]]) – Get projects with this ID. Multiple values are allowed.
rule_details (Optional[bool]) – Return more information about project rules, for example return a full taxon object instead of simply an ID
force_refresh (bool) – Force a refresh of the project record from the API, bypassing both the local and CDN caches

Return type:

Dict[str, Any]

Returns:

Response dict containing project records

pyinaturalist.v1.projects.update_project(project_id, **params)¶

Update a project

Notes

Requires authentication
Undocumented endpoint; may be subject to braking changes in the future

admin_attributes and project_observation_rules_attributes each accept a list of dicts in the formats shown below. These can be obtained from get_projects(), modified, and then passed to this function:

{
    "admin_attributes": [
        {"id": int, "role": str, "user_id": int, "_destroy": bool},
    ],
    "project_observation_rules_attributes": [
        {"operator": str, "operand_type": str, "operand_id": int, "id": int, "_destroy": bool},
    ],
}

Parameters:

project_id (Union[int, str]) – Numeric project ID or slug (the short name shown in project URL)
cover (Optional[str]) – Banner image for project page; ideally 760x320 px
description (Optional[str]) – Description shown on project page
icon (Optional[str]) – Image used as project icon. Should be at least 72x72 px and will be cropped to a square.
preferred_banner_color (Optional[str]) – Background color for project banner, as a RGB hex value (e.g., '#74ac00')
prefers_banner_contain (Optional[bool]) – Fit banner image without cropping
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

>>> update_project(
...     'api-test-project',
...     title='Test Project',
...     description='This is a test project',
...     prefers_rule_native=True,
...     access_token=access_token,
... )

Return type:: Dict[str, Any]
Returns:: The updated project record

prefers_hide_umbrella_map_flags:: prefers_rule_d1: Observation date range to include (start) prefers_rule_d2: Observation date range to include (end) prefers_rule_observed_on: Exact observation date to include prefers_rule_introduced: Only include observations of introduced species prefers_rule_native: Only include observations of native species prefers_rule_members_only: Only include observations of project members prefers_rule_month: Only include observations from these months prefers_rule_photos: Only include observations with photos prefers_rule_sounds: Only include observations with sounds prefers_rule_quality_grade: Only include observations with these quality grades prefers_rule_term_id: Only include observations with this annotation (controlled term ID) prefers_rule_term_value_id: Only include observations with this annotation value (controlled term value ID) prefers_user_trust: Only include observations from trusted users project_type: Project type (‘umbrella’ or ‘collection’) title: Project title user_id: User ID of project owner admin_attributes: Admin users and their roles project_observation_rules_attributes: Rules for observations to include in the project