Projects

Summary

add_project_observation(project_id, ...[, ...])	Add an observation to a project
delete_project_observation(project_id, ...)	Remove an observation from a project
get_projects(**params)	Search projects
get_projects_by_id(project_id[, rule_details])	Get one or more projects by ID

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 (Optional[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 (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.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 (Optional[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 (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)

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 (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, **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]]) – 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

Return type

Dict[str, Any]

Returns

Response dict containing project records