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

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)
Example Response
{
  "id": 54986584,
  "project_id": 24237,
  "observation_id": 81366450,
  "created_at": "2021-07-30T19:10:32.323-05:00",
  "updated_at": "2021-07-30T19:10:32.345-05:00",
  "curator_identification_id": null,
  "tracking_code": null,
  "user_id": 2115051,
  "uuid": "3595235e-96b1-450f-92ec-49162721cc6f",
  "created_at_utc": "2021-07-31T00:10:32.323Z",
  "updated_at_utc": "2021-07-31T00:10:32.345Z"
}
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

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

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

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

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

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