ProjectController

class pyinaturalist.controllers.ProjectController(client)

Bases: BaseController

Controller for Project requests

Methods

__call__(project_id, **kwargs)

Get a single project by ID

Example

>>> client.projects(1234)
Parameters:

project_id (int) – A single project ID

Return type:

Optional[Project]

__init__(client)
add_observations(project_id, observation_ids, **params)

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 (Union[int, Iterable[int]]) – One or more observation IDs to add

Return type:

List[Dict[str, Any]]

add_users(project_id, user_ids, **params)

Add users to project observation rules

Notes

Example

>>> client.projects.add_users(1234, [1234, 5678])
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:

Project

delete_users(project_id, user_ids, **params)

Remove users from project observation rules

Notes

Example

>>> client.projects.delete_users(1234, [1234, 5678])
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:

Project

from_ids(project_ids, **params)

Get projects by ID

Example

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

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

Return type:

Paginator[Project]

search(**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 – Sort order. distance only applies if lat and lng are specified. featured only applies if featured or noteworthy are true.

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',
>>> )
Return type:

Paginator[Project]

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

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

Return type:

Project