ProjectController

class pyinaturalist.controllers.ProjectController(client)

Bases: BaseController

Controller for Project requests

Methods

__call__(project_id, **kwargs) → Project | None

Get a single project by ID

Example

>>> client.projects(1234)
Parameters:

project_id (int) – A single project ID

Return type:

Project | None

__init__(client)
add_observations(project_id, observation_ids, **params) → list[dict[str, Any]]

Add an observation to a project

Notes

Example

>>> client.projects.add_observations(24237, 1234)
Parameters:

  • project_id (int) – ID of project to add onto

  • observation_ids (int | Iterable[int]) – One or more observation IDs to add

Return type:

list[dict[str, Any]]

add_users(project_id, user_ids, **params) → Project

Add users to project observation rules

Notes

Example

>>> client.projects.add_users(1234, [1234, 5678])
Parameters:

  • project_id (int | str) – Either numeric project ID or URL slug

  • user_ids (int | Iterable[int]) – One or more user IDs to add. Only accepts numeric IDs.

Return type:

Project

delete_users(project_id, user_ids, **params) → Project

Remove users from project observation rules

Notes

Example

>>> client.projects.delete_users(1234, [1234, 5678])
Parameters:

  • project_id (int | str) – Either numeric project ID or URL slug

  • user_ids (int | Iterable[int]) – One or more user IDs to remove. Only accepts numeric IDs.

Return type:

Project

from_ids(project_ids, **params) → Paginator[Project]

Get projects by ID

Notes

Example

>>> client.projects.from_id([1234, 5678])
Parameters:

project_ids (int | Iterable[int] | str | Iterable[str]) – One or more project IDs

Return type:

Paginator[Project]

search(q, id, not_id, lat, lng, radius, ...) → Paginator[Project]

Search projects

Notes

Parameters:

  • q (str | None) – Project name must begin with this value

  • id (int | Iterable[int] | None) – Must have this ID

  • not_id (int | Iterable[int] | None) – Must not have this ID

  • lat (float | None) – Must be within a radius kilometer circle around this lat/lng

  • lng (float | None) – 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 (bool | None) – Must be marked featured for the relevant site

  • noteworthy (bool | None) – Must be marked noteworthy for the relevant site

  • place_id (int | Iterable[int] | None) – Must be in the place with this ID

  • site_id (int | None) – Site ID that applies to featured and noteworthy. Defaults to the site of the authenticated user, or to the main iNaturalist site

  • rule_details (bool | None) – Return more information about project rules, for example return a full taxon object instead of simply an ID

  • type (Union[Literal['assessment', 'bioblitz', 'collection', 'umbrella'], Iterable[Literal['assessment', 'bioblitz', 'collection', 'umbrella']], None]) – Projects must be of this type

  • member_id (int | None) – Project must have member with this user ID

  • has_params (bool | None) – Must have search parameter requirements

  • has_posts (bool | None) – Must have posts

  • order_by – Sort order. distance only applies if lat and lng are specified. featured only applies if featured or noteworthy are true.

Return type:

Paginator[Project]

Example

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

>>> client.projects.search(
>>>     q='invasive',
>>>     lat=49.27,
>>>     lng=-123.08,
>>>     radius=400,
>>>     order_by='distance',
>>> )
update(project_id, cover, description, icon, preferred_banner_color, prefers_banner_contain, ...) → Project

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 (int | str) – Numeric project ID or slug (the short name shown in project URL)

  • cover (str | None) – Banner image for project page; ideally 760x320 px

  • description (str | None) – Description shown on project page

  • icon (str | None) – Image used as project icon. Should be at least 72x72 px and will be cropped to a square.

  • preferred_banner_color (str | None) – Background color for project banner, as a RGB hex value (e.g., '#74ac00')

  • prefers_banner_contain (bool | None) – Fit banner image without cropping

Return type:

Project

Example

>>> client.projects.update(
...     'api-test-project',
...     title='Test Project',
...     description='This is a test project',
...     prefers_rule_native=True,
...     access_token=access_token,
... )
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