Observation Fields

Summary

Classes

Functions

get_observation_fields(**params)	Search observation fields.
put_observation_field_values(observation_id, ...)	Set an observation field value on an observation

Module Contents

pyinaturalist.v0.observation_fields.get_observation_fields(**params)

Search observation fields. Observation fields are basically typed data fields that users can attach to observation.

Notes

• API reference: GET /observation_fields

• This endpoint does not support the per_page parameter

Parameters:

• q (Optional[str]) – Search query

• 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 (Optional[str]) – 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

>>> get_observation_fields(q='number of individuals')
>>> # Show just observation field IDs and names
>>> from pprint import pprint
>>> pprint({r['id']: r['name'] for r in response})

Example Response

from datetime import datetime

from dateutil.tz import tzutc

[
    {
        'id': 12822,
        'name': 'Number of individuals (FNAI)',
        'datatype': 'numeric',
        'user_id': 465930,
        'description': 'Number of individuals you counted or estimated',
        'created_at': datetime(2020, 12, 7, 15, 22, 17, 165000, tzinfo=tzutc()),
        'updated_at': datetime(2021, 1, 29, 14, 30, 44, 266000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 5,
        'users_count': 4,
        'uuid': '13f481e7-0389-4c32-80af-44d471f92354',
    },
    {
        'id': 12043,
        'name': 'WOW Number of individuals recorded',
        'datatype': 'numeric',
        'user_id': 3032127,
        'description': 'How many individual orchids did you observe?',
        'created_at': datetime(2020, 5, 24, 11, 0, 55, 54000, tzinfo=tzutc()),
        'updated_at': datetime(2021, 1, 26, 11, 42, 53, 385000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 2274,
        'users_count': 175,
        'uuid': '5441bb80-6bc8-49bd-948d-036fd3e57915',
    },
    {
        'id': 11812,
        'name': 'Number of Individuals?',
        'datatype': 'numeric',
        'user_id': 785779,
        'description': 'How many individuals did you find?',
        'created_at': datetime(2020, 4, 7, 18, 41, 34, 883000, tzinfo=tzutc()),
        'updated_at': datetime(2020, 4, 7, 18, 41, 34, 883000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': None,
        'users_count': None,
        'uuid': '5047f78e-4b89-47a1-b25d-7f4833a9957d',
    },
    {
        'id': 11611,
        'name': 'Number of individuals heard',
        'datatype': 'text',
        'user_id': 394902,
        'description': 'If not visible, number of individuals that are heard and can be identified by sound, eg. amphibians, birds, etc',
        'created_at': datetime(2020, 2, 28, 14, 56, 36, tzinfo=tzutc()),
        'updated_at': datetime(2021, 1, 5, 15, 31, 33, 772000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 5,
        'users_count': 4,
        'uuid': 'ee4863da-3a74-4a07-8292-71cc03e5c245',
    },
    {
        'id': 10774,
        'name': 'Number of individuals observed (precise)',
        'datatype': 'numeric',
        'user_id': 618700,
        'description': '',
        'created_at': datetime(2019, 8, 7, 22, 15, 1, 913000, tzinfo=tzutc()),
        'updated_at': datetime(2019, 8, 7, 22, 15, 1, 913000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': None,
        'users_count': None,
        'uuid': '095b006d-253a-46df-aef2-b72258541a11',
    },
    {
        'id': 10456,
        'name': 'WOWBETA Number of individuals recorded',
        'datatype': 'numeric',
        'user_id': 1591469,
        'description': 'How many individual orchids did you observe?',
        'created_at': datetime(2019, 5, 1, 5, 10, 53, 24000, tzinfo=tzutc()),
        'updated_at': datetime(2020, 5, 24, 11, 0, 52, 967000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 3,
        'users_count': 2,
        'uuid': '57eec037-a17e-4902-a6ce-7e2f11065678',
    },
    {
        'id': 10104,
        'name': 'Number of individuals spotted 8',
        'datatype': 'text',
        'user_id': 1451829,
        'description': '',
        'created_at': datetime(2019, 2, 20, 1, 2, 50, 952000, tzinfo=tzutc()),
        'updated_at': datetime(2019, 11, 17, 18, 31, 42, 103000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 2,
        'users_count': 2,
        'uuid': '672c3324-facc-4013-a980-3a777f742d11',
    },
    {
        'id': 8231,
        'name': 'Number of Individuals in Patch',
        'datatype': 'text',
        'user_id': 19435,
        'description': 'Estimated number of individuals of the same species in the vicinity of inaturalist record',
        'created_at': datetime(2018, 2, 28, 22, 0, 48, 755000, tzinfo=tzutc()),
        'updated_at': datetime(2021, 1, 16, 20, 44, 53, 927000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 413,
        'users_count': 61,
        'uuid': '01660525-dfd9-4145-a7f0-a597d87ac431',
    },
    {
        'id': 7836,
        'name': 'Number of Individuals Detected for the Observed Species',
        'datatype': 'numeric',
        'user_id': 732880,
        'description': "Record a separate observation for each species, along with a total species count for the same  * 10m/30' * section of road and a differentiating letter for each co~occurring detection.",
        'created_at': datetime(2017, 12, 13, 15, 17, 39, 735000, tzinfo=tzutc()),
        'updated_at': datetime(2021, 1, 25, 1, 40, 29, 811000, tzinfo=tzutc()),
        'allowed_values': '1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|>20',
        'values_count': 538,
        'users_count': 2,
        'uuid': 'ed5403f0-e412-4de0-80fd-ece66f75a663',
    },
    {
        'id': 6182,
        'name': 'Maximum number of individuals HEARD ONLY in the first 5 min',
        'datatype': 'numeric',
        'user_id': 423008,
        'description': 'Counts for just the first 5 min of your duration',
        'created_at': datetime(2017, 3, 28, 22, 34, 56, 45000, tzinfo=tzutc()),
        'updated_at': datetime(2018, 6, 13, 10, 35, 38, 439000, tzinfo=tzutc()),
        'allowed_values': '1|2|3',
        'values_count': 7,
        'users_count': 4,
        'uuid': 'ed1728cb-879b-4201-9869-9dd889511442',
    },
    {
        'id': 6181,
        'name': 'Minimum number of individuals HEARD ONLY in the first 5 min',
        'datatype': 'numeric',
        'user_id': 423008,
        'description': 'Counts for just the first 5 min of your duration',
        'created_at': datetime(2017, 3, 28, 22, 34, 12, 315000, tzinfo=tzutc()),
        'updated_at': datetime(2018, 6, 13, 10, 35, 38, 199000, tzinfo=tzutc()),
        'allowed_values': '1|2|3',
        'values_count': 10,
        'users_count': 5,
        'uuid': '0299325a-c171-45a7-a25d-077cc0d9ad2a',
    },
    {
        'id': 6112,
        'name': 'Number of individuals (accurate)',
        'datatype': 'numeric',
        'user_id': 423822,
        'description': 'Precise number of individuals seen.',
        'created_at': datetime(2017, 3, 15, 9, 56, 25, 162000, tzinfo=tzutc()),
        'updated_at': datetime(2020, 10, 18, 16, 54, 37, 344000, tzinfo=tzutc()),
        'allowed_values': '1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|20-30|31-50|51-100|100+',
        'values_count': 106,
        'users_count': 5,
        'uuid': 'a76dbe87-fdc3-4af1-8aae-96641403f89f',
    },
    {
        'id': 5465,
        'name': 'Number of individuals (estimate)',
        'datatype': 'numeric',
        'user_id': 53305,
        'description': '',
        'created_at': datetime(2016, 9, 29, 22, 45, 25, 149000, tzinfo=tzutc()),
        'updated_at': datetime(2020, 4, 29, 20, 35, 47, 61000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 100,
        'users_count': 19,
        'uuid': 'f5c237c9-3f97-4d4e-ab23-5251f3b0a906',
    },
    {
        'id': 4926,
        'name': 'Maximum number of individuals seen at one time during an hour',
        'datatype': 'numeric',
        'user_id': 1115,
        'description': 'This is a simple bird survey method that just asks for the count of the largest number of individuals of a species at a site *seen all at the same time* in an hour.',
        'created_at': datetime(2016, 6, 14, 0, 49, 1, 20000, tzinfo=tzutc()),
        'updated_at': datetime(2020, 11, 22, 10, 52, 5, 968000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 33948,
        'users_count': 11,
        'uuid': '688bf36e-16f0-4484-b5de-5220a221216f',
    },
    {
        'id': 3853,
        'name': 'Number of Individuals at this location',
        'datatype': 'numeric',
        'user_id': 152927,
        'description': 'Best estimate of the total number of individuals at this location',
        'created_at': datetime(2015, 12, 29, 18, 55, 25, 777000, tzinfo=tzutc()),
        'updated_at': datetime(2021, 1, 26, 3, 27, 2, 599000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 522,
        'users_count': 35,
        'uuid': 'ec5d2785-b8a1-4580-bc56-fd70074f7dc8',
    },
    {
        'id': 3838,
        'name': 'Number of Individuals @ Siting',
        'datatype': 'numeric',
        'user_id': 152927,
        'description': 'Please state the number of individual(s) observed at the siting of the same species. Please do not round, and say the exact quantity of organism(s) at the siting.',
        'created_at': datetime(2015, 12, 24, 2, 52, 12, 973000, tzinfo=tzutc()),
        'updated_at': datetime(2018, 4, 22, 23, 23, 49, 771000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 62,
        'users_count': 2,
        'uuid': '7e0977e9-326c-46d9-b1ae-12f88b4dab6d',
    },
    {
        'id': 3751,
        'name': 'Number of Individuals Found',
        'datatype': 'numeric',
        'user_id': 152927,
        'description': 'How many individuals found @ location?',
        'created_at': datetime(2015, 12, 6, 21, 30, 5, 125000, tzinfo=tzutc()),
        'updated_at': datetime(2020, 11, 30, 18, 57, 14, 237000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 78,
        'users_count': 14,
        'uuid': '2bf3a9cf-7764-42bb-a962-2a5f91082101',
    },
    {
        'id': 3102,
        'name': 'Total Number of Individuals - Census',
        'datatype': 'numeric',
        'user_id': 33986,
        'description': 'The number of individuals observed/detected. Estimates should use field below named ESTIMATE. Please enter 999 in this required field if using "ESTIMATE".',
        'created_at': datetime(2015, 8, 7, 23, 16, 34, 573000, tzinfo=tzutc()),
        'updated_at': datetime(2021, 1, 25, 5, 42, 15, 661000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 564,
        'users_count': 29,
        'uuid': '2ded7176-5a2d-4f23-bb32-c1d4c4c41ee4',
    },
    {
        'id': 3081,
        'name': 'ESTIMATE: Total Number of Individuals',
        'datatype': 'text',
        'user_id': 33986,
        'description': 'number of plants in this occurence, if estimate is appropriate',
        'created_at': datetime(2015, 8, 1, 5, 41, 28, 332000, tzinfo=tzutc()),
        'updated_at': datetime(2020, 10, 18, 16, 54, 37, 173000, tzinfo=tzutc()),
        'allowed_values': '1-3|4-10|11-30|31-100|101-300|301-1000|1001-3000|3001-10000|10001-30000|30001+',
        'values_count': 48,
        'users_count': 11,
        'uuid': '76309e72-0641-44a7-a095-b91f8ae189ba',
    },
    {
        'id': 2891,
        'name': 'Monitoring_Plot Species Number of Individuals',
        'datatype': 'numeric',
        'user_id': 5302,
        'description': 'Total number of individuals of nominated species in sample plot',
        'created_at': datetime(2015, 6, 19, 7, 24, 20, 700000, tzinfo=tzutc()),
        'updated_at': datetime(2016, 6, 20, 19, 56, 7, 167000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 11,
        'users_count': 1,
        'uuid': '54275e78-1e5e-49a5-bc73-0c71a7aac328',
    },
    {
        'id': 2866,
        'name': 'Number of Individuals Collected/Observed',
        'datatype': 'numeric',
        'user_id': 109343,
        'description': '',
        'created_at': datetime(2015, 6, 11, 19, 32, 2, 381000, tzinfo=tzutc()),
        'updated_at': datetime(2021, 1, 27, 19, 19, 55, 312000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 4754,
        'users_count': 35,
        'uuid': 'acc6b84c-6498-474e-b19c-6bc0f4eb7086',
    },
    {
        'id': 2134,
        'name': 'Approximate Number of Individuals',
        'datatype': 'numeric',
        'user_id': 43371,
        'description': '',
        'created_at': datetime(2014, 12, 20, 14, 30, 43, 55000, tzinfo=tzutc()),
        'updated_at': datetime(2021, 1, 31, 19, 21, 9, 913000, tzinfo=tzutc()),
        'allowed_values': '1|2|3-5|5-10|10-20|20-50|50-100|100+',
        'values_count': 2184,
        'users_count': 65,
        'uuid': '30b46d87-bc5a-4d8a-bff6-4a62d412f942',
    },
    {
        'id': 1924,
        'name': 'Number of individuals estimated from tracks',
        'datatype': 'numeric',
        'user_id': None,
        'description': None,
        'created_at': datetime(2014, 10, 11, 1, 48, 49, 756000, tzinfo=tzutc()),
        'updated_at': datetime(2020, 11, 1, 19, 12, 22, 48000, tzinfo=tzutc()),
        'allowed_values': None,
        'values_count': 99,
        'users_count': 34,
        'uuid': 'be8c35c6-36fc-4424-994e-b66c66ec2671',
    },
    {
        'id': 1893,
        'name': 'Estimated number of individuals',
        'datatype': 'text',
        'user_id': 59121,
        'description': 'If unable to count how many individuals were present, give your best estimate',
        'created_at': datetime(2014, 6, 18, 2, 49, 11, 372000, tzinfo=tzutc()),
        'updated_at': datetime(2019, 8, 27, 0, 57, 20, 220000, tzinfo=tzutc()),
        'allowed_values': None,
        'values_count': 244,
        'users_count': 20,
        'uuid': '9925f6f1-b343-4d09-94c0-ad748632fabd',
    },
    {
        'id': 1156,
        'name': 'Number of individuals spotted',
        'datatype': 'numeric',
        'user_id': 38289,
        'description': '',
        'created_at': datetime(2014, 5, 19, 8, 26, 55, 913000, tzinfo=tzutc()),
        'updated_at': datetime(2021, 1, 31, 21, 22, 6, 334000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 9848,
        'users_count': 161,
        'uuid': 'b0f297a6-494d-4770-a3d3-32b919884dd9',
    },
    {
        'id': 667,
        'name': 'Number of individuals observed, with sex and life stage if applicable.',
        'datatype': 'text',
        'user_id': 2470,
        'description': "for example, 'at least 10 adult dragonflies observed', '6 clumps, each with 10 to 20 stems', 'one patch of 1.5 square meters, with 8 flowering stems.'",
        'created_at': datetime(2013, 10, 16, 18, 32, 1, 144000, tzinfo=tzutc()),
        'updated_at': datetime(2019, 8, 1, 13, 52, 35, 924000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 3,
        'users_count': 3,
        'uuid': '6f182da0-1e5a-43ea-8c0e-32825d395fd3',
    },
    {
        'id': 546,
        'name': 'Number of individuals observed',
        'datatype': 'text',
        'user_id': 20607,
        'description': 'Approximate number of individuals observed',
        'created_at': datetime(2013, 8, 21, 8, 35, 54, 980000, tzinfo=tzutc()),
        'updated_at': datetime(2021, 1, 29, 21, 12, 24, 962000, tzinfo=tzutc()),
        'allowed_values': '"1-2|3-5|6-10|10-50|more than 50"',
        'values_count': 1324,
        'users_count': 123,
        'uuid': '7ab4e6e6-4ee3-49e6-8adb-9a7df73904d7',
    },
    {
        'id': 1790,
        'name': 'Number of individuals seen after first five minutes',
        'datatype': 'numeric',
        'user_id': 58004,
        'description': 'Your best estimate on the number of individuals seen after first five minutes.',
        'created_at': datetime(2013, 5, 2, 7, 48, 12, 58000, tzinfo=tzutc()),
        'updated_at': datetime(2020, 3, 19, 1, 40, 38, 821000, tzinfo=tzutc()),
        'allowed_values': None,
        'values_count': 2,
        'users_count': 2,
        'uuid': '982aa921-34e9-42a8-85f9-9b004e99ac01',
    },
    {
        'id': 297,
        'name': 'Number of individuals',
        'datatype': 'numeric',
        'user_id': None,
        'description': 'Number of individuals observed together',
        'created_at': datetime(2013, 4, 23, 20, 49, 21, 714000, tzinfo=tzutc()),
        'updated_at': datetime(2021, 1, 31, 23, 41, 3, 494000, tzinfo=tzutc()),
        'allowed_values': '',
        'values_count': 29738,
        'users_count': 1395,
        'uuid': '554a3758-936b-4b91-bb9e-0689d428c939',
    },
    {
        'id': 1776,
        'name': 'Maximum number of individuals SEEN',
        'datatype': 'numeric',
        'user_id': 1115,
        'description': 'Whether you also heard them or not, you need to have seen them to count them here. If you made multiple sightings, this is the maximum number of individuals you could have seen had each sighting been a different individual.',
        'created_at': datetime(2013, 4, 21, 19, 58, 41, 750000, tzinfo=tzutc()),
        'updated_at': datetime(2020, 5, 26, 6, 40, 22, 72000, tzinfo=tzutc()),
        'allowed_values': None,
        'values_count': 2135,
        'users_count': 216,
        'uuid': '9573d60b-b164-4be4-9409-90bcc23730c6',
    },
]

Return type:

Dict[str, Any]

Returns:

Observation fields

pyinaturalist.v0.observation_fields.put_observation_field_values(observation_id, observation_field_id, value, **params)

Set an observation field value on an observation

Notes

• Requires authentication

• API reference: PUT /observation_field_values/{id}

• The request will fail if this observation field is already set for this observation

• To find an observation_field_id, either user get_observation_fields() or search observation fields on iNaturalist

Parameters:

• observation_id (int) – ID of the observation receiving this observation field value

• observation_field_id (int) – ID of the observation field for this observation field value

• value (Any) – Value for the observation field

• access_token (Optional[str]) – An access token for user authentication, as returned by get_access_token()

• 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

>>> # First find an observation field by name, if the ID is unknown
>>> response = get_observation_fields('vespawatch_id')
>>> observation_field_id = response[0]['id']

>>> put_observation_field_values(
...     observation_id=7345179,
...     observation_field_id=observation_field_id,
...     value=250,
...     access_token=token,
... )

Example Response

{
  "id": 31,
  "observation_id": 18166477,
  "observation_field_id": 31,
  "value": "fouraging",
  "created_at": "2012-09-29T11:05:44.935+02:00",
  "updated_at": "2018-11-13T10:49:47.985+01:00",
  "user_id": 1,
  "updater_id": 1263313,
  "uuid": "b404b654-1bf0-4299-9288-52eeda7ac0db",
  "created_at_utc": "2012-09-29T09:05:44.935Z",
  "updated_at_utc": "2018-11-13T09:49:47.985Z"
}

Return type:

Dict[str, Any]

Returns:

The newly updated field value record