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:

Optional[Project]

__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 (Union[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 (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) → Project

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) → Paginator[Project]

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(q=None, id=None, not_id=None, lat=None, lng=None, radius=500, featured=None, noteworthy=None, place_id=None, site_id=None, rule_details=None, type=None, member_id=None, has_params=None, has_posts=None, **kwargs) → Paginator[Project]

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.

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=None, description=None, icon=None, preferred_banner_color=None, prefers_banner_contain=None, prefers_hide_title=None, prefers_hide_umbrella_map_flags=None, prefers_rule_d1=None, prefers_rule_d2=None, prefers_rule_introduced=None, prefers_rule_members_only=None, prefers_rule_month=None, prefers_rule_native=None, prefers_rule_observed_on=None, prefers_rule_photos=None, prefers_rule_quality_grade=None, prefers_rule_sounds=None, prefers_rule_term_id=None, prefers_rule_term_value_id=None, prefers_user_trust=None, project_type=None, title=None, user_id=None, admin_attributes=None, project_observation_rules_attributes=None, **kwargs) → 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 (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

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