pyinaturalist.rest_api module

Code used to access the (read/write, but slow) Rails based API of iNaturalist See: https://www.inaturalist.org/pages/api+reference

Functions

get_observations	Get observation data, optionally in an alternative format.
get_observation_fields	Search observation fields.
put_observation_field_values	Set an observation field (value) on an observation.
create_observation	Create a new observation.
update_observation	Update a single observation.
add_photo_to_observation	Upload a local photo and assign it to an existing observation.
delete_observation	Delete an observation.

pyinaturalist.rest_api.add_photo_to_observation(observation_id, photo, access_token, user_agent=None)

Upload a local photo and assign it to an existing observation.

API reference: https://www.inaturalist.org/pages/api+reference#post-observation_photos

Example

>>> token = get_access_token()
>>> add_photo_to_observation(
>>>     1234,
>>>     '~/observation_photos/2020_09_01_14003156.jpg',
>>>     access_token=token,
>>> )

Example Response

{
    "id": 1234,
    "observation_id": 1234,
    "photo_id": 1234,
    "position": null,
    "created_at": "2020-09-24T21:06:16.964-05:00",
    "updated_at": "2020-09-24T21:06:16.964-05:00",
    "old_uuid": null,
    "uuid": "f4ec883f-e835-4590-ab3e-97900bd454a5",
    "created_at_utc": "2020-09-25T02:06:16.964Z",
    "updated_at_utc": "2020-09-25T02:06:16.964Z",
    "photo": {
        "id": 1234,
        "user_id": 1234,
        "native_photo_id": "1234",
        "square_url": null,
        "thumb_url": null,
        "small_url": null,
        "medium_url": null,
        "large_url": null,
        "created_at": "2020-09-24T21:06:15.212-05:00",
        "updated_at": "2020-09-24T21:06:15.212-05:00",
        "native_page_url": null,
        "native_username": "username",
        "native_realname": "Firstname Lastname",
        "license": 2,
        "subtype": null,
        "native_original_image_url": null,
        "uuid": "632dddc1-85ad-4664-8438-de6e0afd7746",
        "license_name": "Creative Commons Attribution-NonCommercial License",
        "license_url": "http://creativecommons.org/licenses/by-nc/4.0/",
        "attribution": "(c) Firstname Lastname, some rights reserved (CC BY-NC)",
        "type": "LocalPhoto"
    }
}

Parameters

• observation_id (int) – the ID of the observation

• photo (Union[BinaryIO, str]) – An image file, file-like object, or path

• access_token (str) – the access token, as returned by get_access_token()

• user_agent (Optional[str]) – a user-agent string that will be passed to iNaturalist.

Returns

Information about the newly created photo

pyinaturalist.rest_api.create_observation(access_token=None, **params)

Create a new observation.

API reference: https://www.inaturalist.org/pages/api+reference#post-observations

Example

>>> token = get_access_token()
>>> create_observation(
>>>     access_token=token,
>>>     species_guess='Pieris rapae',
>>>     local_photos='~/observation_photos/2020_09_01_14003156.jpg',
>>>     observation_fields={297: 1},  # 297 is the obs. field ID for 'Number of individuals'
>>> )

Example Response

[
  {
    "id": 18124406,
    "observed_on": null,
    "description": null,
    "latitude": null,
    "longitude": null,
    "map_scale": null,
    "timeframe": null,
    "species_guess": "Pieris rapae",
    "user_id": 1263313,
    "taxon_id": 55626,
    "created_at": "2018-11-05T11:08:19.150+01:00",
    "updated_at": "2018-11-05T11:08:19.215+01:00",
    "place_guess": null,
    "id_please": false,
    "observed_on_string": null,
    "iconic_taxon_id": 47158,
    "num_identification_agreements": 0,
    "num_identification_disagreements": 0,
    "time_observed_at": null,
    "time_zone": "Brussels",
    "location_is_exact": false,
    "delta": false,
    "positional_accuracy": null,
    "private_latitude": null,
    "private_longitude": null,
    "private_positional_accuracy": null,
    "geoprivacy": null,
    "quality_grade": "casual",
    "positioning_method": null,
    "positioning_device": null,
    "out_of_range": null,
    "license": "CC-BY-NC",
    "uri": null,
    "observation_photos_count": 0,
    "comments_count": 0,
    "zic_time_zone": "Europe/Brussels",
    "oauth_application_id": 278,
    "observation_sounds_count": 0,
    "identifications_count": 1,
    "captive": false,
    "community_taxon_id": null,
    "site_id": 1,
    "old_uuid": null,
    "public_positional_accuracy": null,
    "mappable": false,
    "cached_votes_total": 0,
    "last_indexed_at": "2018-11-05T02:08:19.652-08:00",
    "private_place_guess": null,
    "uuid": "0f0581ce-1be5-4ba5-9d0b-ecac994b50ed",
    "user_login": "vespawatch",
    "iconic_taxon_name": "Insecta",
    "project_observations": [],
    "created_at_utc": "2018-11-05T10:08:19.150Z",
    "updated_at_utc": "2018-11-05T10:08:19.215Z",
    "time_observed_at_utc": null,
    "faves_count": 0,
    "owners_identification_from_vision": false
  }
]

Example Response (failure)

{
  "errors": [
    [
      "Observed on can't be in the future",
      "Latitude doit être inférieur ou égal à 90"
    ]
  ]
}

Parameters

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

• species_guess (str) – Equivalent to the ‘What did you see?’ field on the observation form. iNat will try to choose a single taxon based on this, but it may fail if it’s ambuguous

• taxon_id (int) – ID of the taxon to associate with this observation

• observed_on_string (Union[datetime.date, datetime.datetime, str]) – Date/time of the observation. Time zone will default to the user’s time zone if not specified.

• time_zone (str) – Time zone the observation was made in

• description (str) – Observation description

• tag_list (Union[str, List[str]]) – Comma-separated list of tags

• place_guess (str) – Name of the place where the observation was recorded. Note: iNat will not try to automatically look up coordinates based on this string

• latitude (float) – Latitude of the observation; presumed datum is WGS84

• longitude (float) – Longitude of the observation; presumed datum is WGS84

• map_scale (int) – Google Maps zoom level (from 0 to 19) at which to show this observation’s map marker.

• positional_accuracy (int) – Positional accuracy of the observation coordinates, in meters

• geoprivacy (str) – Geoprivacy for the observation

• observation_fields (Union[Dict, List[Dict]]) – Dict of observation fields in the format {id: value}. Alias for observation_field_values_attributes.

• flickr_photos (Union[int, List[int]]) – Flickr photo ID(s) to add as photos for this observation. User must have their Flickr and iNat accounts connected, and the user must own the photo(s) on Flickr.

• picasa_photos (Union[str, List[str]]) – Picasa photo ID(s) to add as photos for this observation. User must have their Picasa and iNat accounts connected, and the user must own the photo(s) on Picasa.

• facebook_photos (Union[str, List[str]]) – Facebook photo IDs to add as photos for this observation. User must have their Facebook and iNat accounts connected, and the user must own the photo on Facebook.

• local_photos (Iterable[Union[BinaryIO, str]]) – Image files, file-like objects, and/or paths for local photos to upload

• user_agent (str) – A custom user-agent string to provide to the iNaturalist API

• observation_field_values_attributes (Union[Dict, List[Dict]]) –

Return type

List[Dict[str, Any]]

Returns

JSON response containing the newly created observation(s)

Raises

• requests.HTTPError –

• error 422 (unprocessable entity) if it rejects the observation data (for example an –

• observation date in the future or a latitude > 90. In that case the exception's –

• response` attribute gives more details about the errors –

pyinaturalist.rest_api.delete_observation(observation_id, access_token=None, user_agent=None)

Delete an observation.

API reference: https://www.inaturalist.org/pages/api+reference#delete-observations-id

Example

>>> token = get_access_token()
>>> delete_observation(17932425, token)

Parameters

• observation_id (int) – iNaturalist observation ID

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

• user_agent (Optional[str]) – A custom user-agent string to provide to the iNaturalist API

Returns

If successful, no response is returned from this endpoint

Raises

• ObservationNotFound –

• requests.HTTPError –

pyinaturalist.rest_api.get_access_token(username=None, password=None, app_id=None, app_secret=None, user_agent=None)

Get an access token using the user’s iNaturalist username and password. You still need an iNaturalist app to do this.

API reference: https://www.inaturalist.org/pages/api+reference#auth

See Authentication for additional options for storing credentials.

Examples

With direct keyword arguments:

>>> from pyinaturalist.auth import get_access_token
>>> access_token = get_access_token(
>>>     username='my_username',
>>>     password='my_password',
>>>     app_id='33f27dc63bdf27f4ca6cd95dd9dcd5df',
>>>     app_secret='bbce628be722bfe2abd5fc566ba83de4',
>>> )

With environment variables or keyring configured:

>>> access_token = get_access_token()

If you would like to run custom requests for endpoints not yet implemented in pyinaturalist, you can authenticate these requests by putting the token in your HTTP headers as follows:

>>> import requests
>>> requests.get(
>>>     'https://www.inaturalist.org/observations/1234',
>>>      headers={'Authorization': f'Bearer {access_token}'},
>>> )

Parameters

• username (Optional[str]) – iNaturalist username

• password (Optional[str]) – iNaturalist password

• app_id (Optional[str]) – iNaturalist application ID

• app_secret (Optional[str]) – iNaturalist application secret

• user_agent (Optional[str]) – a user-agent string that will be passed to iNaturalist.

Raises

requests.HTTPError –

Return type

str

pyinaturalist.rest_api.get_observation_fields(**params)

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

API reference: https://www.inaturalist.org/pages/api+reference#get-observation_fields

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',
    },
]

Parameters

• q (str) – Search query

• page (int) – Page number of results to return

• per_page (int) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted

• order (str) – Sort order

• order_by (str) – Field to sort on

• count_only (bool) – Only return a count of results; alias for per_page=0

• user_agent (str) – A custom user-agent string to provide to the iNaturalist API

Return type

Dict[str, Any]

Returns

Observation fields as a list of dicts

pyinaturalist.rest_api.get_observations(**params)

Get observation data, optionally in an alternative format. Also see get_geojson_observations() for GeoJSON format (not included here because it wraps a separate API endpoint).

API reference: https://www.inaturalist.org/pages/api+reference#get-observations

Example

>>> get_observations(id=45414404, response_format='atom')

Example Response (atom)

<?xml version="1.0" encoding="UTF-8"?>
<feed xml:lang="en-US" xmlns="http://www.w3.org/2005/Atom" xmlns:georss="http://www.georss.org/georss">
  <id>tag:www.inaturalist.org,2005:/observations</id>
  <link rel="alternate" type="text/html" href="https://www.inaturalist.org"/>
  <link rel="self" type="application/atom+xml" href="https://www.inaturalist.org/observations.atom?id=16227955"/>
  <title>iNaturalist: Observations by Everyone</title>
  <updated>2020-06-10T23:05:37Z</updated>
  <icon>/assets/favicon-cf3214988200dff386f744b79050b857.png</icon>
  <entry>
    <id>tag:www.inaturalist.org,2005:Observation/16227955</id>
    <published>2018-09-05T12:31:08Z</published>
    <updated>2018-09-22T17:19:27Z</updated>
    <link rel="alternate" type="text/html" href="https://www.inaturalist.org/observations/16227955"/>
    <title>Lixus bardanae</title>
    <author>
      <name>niconoe</name>
    </author>
    <content type="html">&lt;p&gt;&lt;img src="https://static.inaturalist.org/photos/24355313/medium.jpeg?1536150659" alt="Medium" /&gt; &lt;img src="https://static.inaturalist.org/photos/24355315/medium.jpeg?1536150664" alt="Medium" /&gt;&lt;/p&gt;&lt;p&gt;&lt;/p&gt;</content>
    <georss:point>50.646894 4.360086</georss:point>
  </entry>
</feed>

Example Response (csv)

scientific_name,datetime,description,place_guess,latitude,longitude,tag_list,common_name,url,image_url,user_login,id,species_guess,iconic_taxon_name,taxon_id,num_identification_agreements,num_identification_disagreements,observed_on_string,observed_on,time_observed_at,time_zone,positional_accuracy,private_place_guess,geoprivacy,taxon_geoprivacy,coordinates_obscured,positioning_method,positioning_device,user_id,created_at,updated_at,quality_grade,license,sound_url,oauth_application_id,captive_cultivated
Lixus bardanae,2018-09-05 14:06:00 +0200,"",54 rue des Badauds,50.646894,4.360086,"",,https://www.inaturalist.org/observations/16227955,https://static.inaturalist.org/photos/24355315/medium.jpeg?1536150664,niconoe,16227955,Lixus bardanae,Insecta,493595,2,0,2018/09/05 2:06 PM CEST,2018-09-05,2018-09-05 12:06:00 UTC,Paris,23,,,,false,,,886482,2018-09-05 12:31:08 UTC,2018-09-22 17:19:27 UTC,research,CC0,,,false

Example Response (dwc)

<?xml version="1.0" encoding="UTF-8"?>
<dwr:SimpleDarwinRecordSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://rs.tdwg.org/dwc/xsd/simpledarwincore/  http://rs.tdwg.org/dwc/xsd/tdwg_dwc_simple.xsd" xmlns:ac="http://rs.tdwg.org/ac/terms/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:dwc="http://rs.tdwg.org/dwc/terms/" xmlns:dwr="http://rs.tdwg.org/dwc/xsd/simpledarwincore/" xmlns:eol="http://www.eol.org/transfer/content/1.0" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#" xmlns:media="http://eol.org/schema/media/" xmlns:ref="http://eol.org/schema/reference/" xmlns:xap="http://ns.adobe.com/xap/1.0/">
<dwr:SimpleDarwinRecord>
  <dwc:occurrenceID>https://www.inaturalist.org/observations/16227955</dwc:occurrenceID>
  <dwc:occurrenceID>https://www.inaturalist.org/observations/16227955</dwc:occurrenceID>
  <dwc:basisOfRecord>HumanObservation</dwc:basisOfRecord>
  <dcterms:modified>2018-09-22T17:19:27Z</dcterms:modified>
  <dwc:institutionCode>iNaturalist</dwc:institutionCode>
  <dwc:collectionCode>Observations</dwc:collectionCode>
  <dwc:datasetName>iNaturalist research-grade observations</dwc:datasetName>
  <dwc:catalogNumber>16227955</dwc:catalogNumber>
  <dcterms:references>https://www.inaturalist.org/observations/16227955</dcterms:references>
  <dwc:occurrenceDetails>https://www.inaturalist.org/observations/16227955</dwc:occurrenceDetails>
  <dwc:recordedBy>Nicolas Noé</dwc:recordedBy>
  <dwc:establishmentMeans>wild</dwc:establishmentMeans>
  <dwc:eventDate>2018-09-05T14:06:00+02:00</dwc:eventDate>
  <dwc:eventTime>12:06:00Z</dwc:eventTime>
  <dwc:verbatimEventDate>2018/09/05 2:06 PM CEST</dwc:verbatimEventDate>
  <dwc:verbatimLocality>54 rue des Badauds</dwc:verbatimLocality>
  <dwc:decimalLatitude>50.646894</dwc:decimalLatitude>
  <dwc:decimalLongitude>4.360086</dwc:decimalLongitude>
  <dwc:coordinateUncertaintyInMeters>23</dwc:coordinateUncertaintyInMeters>
  <dwc:countryCode>BE</dwc:countryCode>
  <dwc:stateProvince>Wallonie</dwc:stateProvince>
  <dwc:identificationID>34896306</dwc:identificationID>
  <dwc:dateIdentified>2018-09-05T12:34:22Z</dwc:dateIdentified>
  <dwc:taxonID>493595</dwc:taxonID>
  <dwc:scientificName>Lixus bardanae</dwc:scientificName>
  <dwc:taxonRank>species</dwc:taxonRank>
  <dwc:kingdom>Animalia</dwc:kingdom>
  <dwc:phylum>Arthropoda</dwc:phylum>
  <dwc:class>Insecta</dwc:class>
  <dwc:order>Coleoptera</dwc:order>
  <dwc:family>Curculionidae</dwc:family>
  <dwc:genus>Lixus</dwc:genus>
  <dcterms:license>http://creativecommons.org/publicdomain/zero/1.0/</dcterms:license>
  <dcterms:rights>By Nicolas Noé no rights reserved</dcterms:rights>
  <dcterms:rightsHolder>Nicolas Noé</dcterms:rightsHolder>
  <dwc:inaturalistLogin>niconoe</dwc:inaturalistLogin>
  <eol:dataObject>
    <dcterms:identifier>https://www.inaturalist.org/photos/24355313</dcterms:identifier>
    <dcterms:type>http://purl.org/dc/dcmitype/StillImage</dcterms:type>
    <dcterms:format>image/jpeg</dcterms:format>
    <ac:accessURI>https://static.inaturalist.org/photos/24355313/original.jpeg?1536150659</ac:accessURI>
    <media:thumbnailURL>https://static.inaturalist.org/photos/24355313/thumb.jpeg?1536150659</media:thumbnailURL>
    <ac:furtherInformationURL>https://www.inaturalist.org/photos/24355313</ac:furtherInformationURL>
    <ac:derivedFrom>https://www.inaturalist.org/photos/24355313</ac:derivedFrom>
    <xap:CreateDate>2018-09-05T12:31:01Z</xap:CreateDate>
    <dcterms:modified>2018-09-05T12:31:01Z</dcterms:modified>
    <xap:UsageTerms>http://creativecommons.org/licenses/by/4.0/</xap:UsageTerms>
    <dcterms:rights>Copyright Nicolas Noé, licensed under a Creative Commons Attribution License license: http://creativecommons.org/licenses/by/4.0/</dcterms:rights>
    <xap:Owner>Nicolas Noé</xap:Owner>
    <dcterms:publisher>iNaturalist</dcterms:publisher>
    <dcterms:creator>Nicolas Noé</dcterms:creator>
  </eol:dataObject>
  <eol:dataObject>
    <dcterms:identifier>https://www.inaturalist.org/photos/24355315</dcterms:identifier>
    <dcterms:type>http://purl.org/dc/dcmitype/StillImage</dcterms:type>
    <dcterms:format>image/jpeg</dcterms:format>
    <ac:accessURI>https://static.inaturalist.org/photos/24355315/original.jpeg?1536150664</ac:accessURI>
    <media:thumbnailURL>https://static.inaturalist.org/photos/24355315/thumb.jpeg?1536150664</media:thumbnailURL>
    <ac:furtherInformationURL>https://www.inaturalist.org/photos/24355315</ac:furtherInformationURL>
    <ac:derivedFrom>https://www.inaturalist.org/photos/24355315</ac:derivedFrom>
    <xap:CreateDate>2018-09-05T12:31:05Z</xap:CreateDate>
    <dcterms:modified>2018-09-05T12:31:05Z</dcterms:modified>
    <xap:UsageTerms>http://creativecommons.org/licenses/by/4.0/</xap:UsageTerms>
    <dcterms:rights>Copyright Nicolas Noé, licensed under a Creative Commons Attribution License license: http://creativecommons.org/licenses/by/4.0/</dcterms:rights>
    <xap:Owner>Nicolas Noé</xap:Owner>
    <dcterms:publisher>iNaturalist</dcterms:publisher>
    <dcterms:creator>Nicolas Noé</dcterms:creator>
  </eol:dataObject>
</dwr:SimpleDarwinRecord>
</dwr:SimpleDarwinRecordSet>

Example Response (json)

[
    {
        "id": 16227955,
        "observed_on": "2018-09-05",
        "description": "",
        "latitude": "50.646894",
        "longitude": "4.360086",
        "map_scale": 17,
        "timeframe": null,
        "species_guess": "Lixus bardanae",
        "user_id": 886482,
        "taxon_id": 493595,
        "created_at": "2018-09-05T12:31:08.048Z",
        "updated_at": "2018-09-22T17:19:27.080Z",
        "place_guess": "54 rue des Badauds",
        "id_please": false,
        "observed_on_string": "2018/09/05 2:06 PM CEST",
        "iconic_taxon_id": 47158,
        "num_identification_agreements": 2,
        "num_identification_disagreements": 0,
        "time_observed_at": "2018-09-05T12:06:00.000Z",
        "time_zone": "Paris",
        "location_is_exact": true,
        "delta": false,
        "positional_accuracy": 23,
        "private_latitude": null,
        "private_longitude": null,
        "private_positional_accuracy": null,
        "geoprivacy": null,
        "quality_grade": "research",
        "positioning_method": null,
        "positioning_device": null,
        "out_of_range": null,
        "license": "CC0",
        "uri": "https://www.inaturalist.org/observations/16227955",
        "observation_photos_count": 2,
        "comments_count": 2,
        "zic_time_zone": "Europe/Paris",
        "oauth_application_id": null,
        "observation_sounds_count": 0,
        "identifications_count": 3,
        "captive": false,
        "community_taxon_id": 493595,
        "site_id": 1,
        "old_uuid": null,
        "public_positional_accuracy": 23,
        "mappable": true,
        "cached_votes_total": 0,
        "last_indexed_at": "2019-10-10T20:19:39.304Z",
        "private_place_guess": null,
        "uuid": "6448d03a-7f9a-4099-86aa-ca09a7740b00",
        "taxon_geoprivacy": null,
        "short_description": "",
        "user_login": "niconoe",
        "iconic_taxon_name": "Insecta",
        "tag_list": [],
        "faves_count": 0,
        "created_at_utc": "2018-09-05T12:31:08.048Z",
        "updated_at_utc": "2018-09-22T17:19:27.080Z",
        "time_observed_at_utc": "2018-09-05T12:06:00.000Z",
        "owners_identification_from_vision": true,
        "taxon": {
            "id": 493595,
            "name": "Lixus bardanae",
            "rank": "species",
            "ancestry": "48460/1/47120/372739/47158/184884/47208/71130/372852/60473/48736/272543/507383/71157",
            "common_name": null
        },
        "iconic_taxon": {
            "id": 47158,
            "name": "Insecta",
            "rank": "class",
            "rank_level": 50.0,
            "ancestry": "48460/1/47120/372739"
        },
        "user": {
            "login": "niconoe",
            "user_icon_url": "https://static.inaturalist.org/attachments/users/icons/886482/thumb.jpg?1529671435"
        },
        "photos": [
            {
                "id": 24355313,
                "user_id": 886482,
                "native_photo_id": "24355313",
                "square_url": "https://static.inaturalist.org/photos/24355313/square.jpeg?1536150659",
                "thumb_url": "https://static.inaturalist.org/photos/24355313/thumb.jpeg?1536150659",
                "small_url": "https://static.inaturalist.org/photos/24355313/small.jpeg?1536150659",
                "medium_url": "https://static.inaturalist.org/photos/24355313/medium.jpeg?1536150659",
                "large_url": "https://static.inaturalist.org/photos/24355313/large.jpeg?1536150659",
                "created_at": "2018-09-05T12:31:01.946Z",
                "updated_at": "2018-09-05T12:31:01.946Z",
                "native_page_url": "https://www.inaturalist.org/photos/24355313",
                "native_username": "niconoe",
                "native_realname": "Nicolas No\u00e9",
                "license": 4,
                "subtype": null,
                "native_original_image_url": null,
                "uuid": "be0dcd96-db21-4c19-814b-bcd33c051ea6",
                "license_code": "CC-BY",
                "attribution": "(c) Nicolas No\u00e9, some rights reserved (CC BY)",
                "license_name": "Creative Commons Attribution License",
                "license_url": "http://creativecommons.org/licenses/by/4.0/",
                "type": "LocalPhoto"
            },
            {
                "id": 24355315,
                "user_id": 886482,
                "native_photo_id": "24355315",
                "square_url": "https://static.inaturalist.org/photos/24355315/square.jpeg?1536150664",
                "thumb_url": "https://static.inaturalist.org/photos/24355315/thumb.jpeg?1536150664",
                "small_url": "https://static.inaturalist.org/photos/24355315/small.jpeg?1536150664",
                "medium_url": "https://static.inaturalist.org/photos/24355315/medium.jpeg?1536150664",
                "large_url": "https://static.inaturalist.org/photos/24355315/large.jpeg?1536150664",
                "created_at": "2018-09-05T12:31:05.862Z",
                "updated_at": "2018-09-05T12:31:05.862Z",
                "native_page_url": "https://www.inaturalist.org/photos/24355315",
                "native_username": "niconoe",
                "native_realname": "Nicolas No\u00e9",
                "license": 4,
                "subtype": null,
                "native_original_image_url": null,
                "uuid": "154b105a-3e04-448d-b8a3-8ced07af2adf",
                "license_code": "CC-BY",
                "attribution": "(c) Nicolas No\u00e9, some rights reserved (CC BY)",
                "license_name": "Creative Commons Attribution License",
                "license_url": "http://creativecommons.org/licenses/by/4.0/",
                "type": "LocalPhoto"
            }
        ]
    }
]

Example Response (kml)

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom">
  <Document>
<Placemark id="ID16227955">
  <name>Lixus bardanae</name>
  <visibility>1</visibility>
  <atom:link>https://www.inaturalist.org/observations/16227955</atom:link>
  <TimeStamp>
    <when>2018-09-05T14:06:00+02:00</when>
  </TimeStamp>
  <description>
    <![CDATA[<table cellpadding="5" border="0">
  <tr>
    <td valign="top" style="vertical-align: top">
      <a href="https://www.inaturalist.org/observations/16227955">
        <img src="https://static.inaturalist.org/photos/24355315/thumb.jpeg?1536150664" alt="Thumb" />
      </a>
    </td>
    <td valign="top" style="vertical-align: top">
      <div>
        Observed by <a href="https://www.inaturalist.org/observations/niconoe">niconoe</a>

          <span class="observed_on"><span class="date">2018-09-05</span></span>
          <span class="place_guess">54 rue des Badauds</span>
        <br/>
        <br/>
      </div>



      <div>
        <a class="readmore" href="https://www.inaturalist.org/observations/16227955">View Observation</a>
      </div>
    </td>
  </tr>
</table>
]]>
  </description>
  <styleUrl>/assets/observations/google_earth-824f44474a896e5afd52c3274499151b.kml?prevent=155#Insecta</styleUrl>
  <Point>
    <coordinates>4.360086,50.646894</coordinates>
  </Point>
</Placemark>
  </Document>
</kml>

Example Response (widget)

try {
  var msg = document.getElementById('inatwidgetmsg');
    if (msg) {
      msg.style.visibility = 'visible';
    }

      document.write('<table data-current-page=\"1\" data-per-page=\"30\" data-total-entries=\"1\"data-total-pages=\"1\"><tr class=\"inat-observation\"><td class=\"inat-observation-image\" valign=\"top\" align=\"center\"><a href=\"https://www.inaturalist.org/observations/16227955\"><img border=\"0\" title=\"Lixus bardanae from 54 rue des Badauds on September 05, 2018 at 02:06 PM by Nicolas Noé\" src=\"https://static.inaturalist.org/photos/24355315/square.jpeg?1536150664\" alt=\"Square\" /><\/a>      <\/td><td class=\"inat-observation-body\" valign=\"top\"><a href=\"https://www.inaturalist.org/observations/16227955\">Lixus bardanae<\/a><div class=\"inat-meta\"><span class=\"inat-label\">Observer: <\/span><span class=\"inat-value\"><a href=\"https://www.inaturalist.org/observations/niconoe\">niconoe<\/a><\/span><br/><span class=\"inat-label\">Date: <\/span><span class=\"inat-value\"> Sep 05 2018<\/span><br/><span class=\"inat-label\">Place: <\/span><span class=\"inat-value\">54 rue des Badauds<\/span><\/div><\/td><\/tr><\/table>')


} catch (e) {}

Parameters

• q (str) – Search observation properties

• d1 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or after this date

• d2 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or before this date

• day (Union[int, List[int]]) – Must be observed within this day of the month

• month (Union[int, List[int]]) – Must be observed within this month

• year (Union[int, List[int]]) – Must be observed within this year

• license (Union[str, List[str]]) – Observation must have this license

• photo_license (Union[str, List[str]]) – Must have at least one photo with this license

• out_of_range (bool) – Observations whose taxa are outside their known ranges

• list_id (int) – Taxon must be in the list with this ID

• quality_grade (str) – Must have this quality grade

• id (Union[int, List[int]]) – Must have this observation ID

• taxon_id (Union[int, List[int]]) – Only show observations of these taxa and their descendants

• taxon_name (Union[str, List[str]]) – Taxon must have a scientific or common name matching this string

• iconic_taxa (Union[str, List[str]]) – Taxon must by within this iconic taxon

• updated_since (Union[datetime.date, datetime.datetime, str]) – Must be updated since this time

• has (Union[str, List[str]]) – Catch-all for some boolean selectors. This can be used multiple times, e.g. has=['photos', 'geo']

• m1 (Union[datetime.date, datetime.datetime, str]) – First month of a month range

• m2 (Union[datetime.date, datetime.datetime, str]) – Last month of a month range

• h1 (Union[datetime.date, datetime.datetime, str]) – First hour of an hour range

• h2 (Union[datetime.date, datetime.datetime, str]) – Last hour of an hour range

• on (Union[datetime.date, datetime.datetime, str]) – Filter by date string

• extra (str) – Retrieve additional information. ‘projects’ returns info about the projects the observations have been added to, ‘fields’ returns observation field values, ‘observation_photos’ returns information about the photos’ relationship with the observation, like their order.

• response_format (str) – A supported response format to return

• nelat (float) – NE latitude of bounding box

• nelng (float) – NE longitude of bounding box

• swlat (float) – SW latitude of bounding box

• swlng (float) – SW longitude of bounding box

• page (int) – Page number of results to return

• per_page (int) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted

• order (str) – Sort order

• order_by (str) – Field to sort on

• count_only (bool) – Only return a count of results; alias for per_page=0

• user_agent (str) – A custom user-agent string to provide to the iNaturalist API

Return type

Union[List, str]

Returns

Return type will be dict for the json response format, and str for all others.

pyinaturalist.rest_api.put_observation_field_values(observation_id, observation_field_id, value, access_token, user_agent=None)

Set an observation field (value) on an observation. 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 on iNaturalist: https://www.inaturalist.org/observation_fields

API reference: https://www.inaturalist.org/pages/api+reference#put-observation_field_values-id

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"
}

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 (str) – access_token: The access token, as returned by get_access_token()

• user_agent (Optional[str]) – A user-agent string that will be passed to iNaturalist.

Return type

Dict[str, Any]

Returns

The newly updated field value record

pyinaturalist.rest_api.update_observation(observation_id, access_token=None, **params)

Update a single observation.

API reference: https://www.inaturalist.org/pages/api+reference#put-observations-id

Note

Unlike the underlying REST API endpoint, this function will not delete any existing photos from your observation if not specified in local_photos. If you want this to behave the same as the REST API and you do want to delete photos, call with ignore_photos=False.

Example

>>> token = get_access_token()
>>> update_observation(
>>>     17932425,
>>>     access_token=token,
>>>     description='updated description!',
>>> )

Example Response

[
  {
    "id": 17932425,
    "observed_on": "2018-10-29",
    "description": "updated description v2 !",
    "latitude": "50.4898053873",
    "longitude": "5.1035889611",
    "map_scale": null,
    "timeframe": null,
    "species_guess": null,
    "user_id": 1263313,
    "taxon_id": 54327,
    "created_at": "2018-10-29T14:37:32.176+01:00",
    "updated_at": "2018-10-30T14:30:11.667+01:00",
    "place_guess": "Namur, Wallonie, BE",
    "id_please": false,
    "observed_on_string": "2018-10-28T23:00:00+00:00",
    "iconic_taxon_id": 47158,
    "num_identification_agreements": 0,
    "num_identification_disagreements": 0,
    "time_observed_at": "2018-10-29T00:00:00.000+01:00",
    "time_zone": "Brussels",
    "location_is_exact": false,
    "delta": false,
    "positional_accuracy": null,
    "private_latitude": null,
    "private_longitude": null,
    "private_positional_accuracy": null,
    "geoprivacy": null,
    "quality_grade": "casual",
    "positioning_method": null,
    "positioning_device": null,
    "out_of_range": null,
    "license": "CC-BY-NC",
    "uri": "https://www.inaturalist.org/observations/17932425",
    "observation_photos_count": 0,
    "comments_count": 0,
    "zic_time_zone": "Europe/Brussels",
    "oauth_application_id": 278,
    "observation_sounds_count": 0,
    "identifications_count": 1,
    "captive": false,
    "community_taxon_id": null,
    "site_id": 1,
    "old_uuid": null,
    "public_positional_accuracy": null,
    "mappable": true,
    "cached_votes_total": 0,
    "last_indexed_at": "2018-10-30T06:36:06.027-07:00",
    "private_place_guess": null,
    "uuid": "03d9e7a4-d96e-4de0-a9ec-d1dacc14be44",
    "user_login": "vespawatch",
    "iconic_taxon_name": "Insecta",
    "created_at_utc": "2018-10-29T13:37:32.176Z",
    "updated_at_utc": "2018-10-30T13:30:11.667Z",
    "time_observed_at_utc": "2018-10-28T23:00:00.000Z",
    "faves_count": 0,
    "owners_identification_from_vision": false
  }
]

Parameters

• observation_id (int) – iNaturalist observation ID

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

• species_guess (str) – Equivalent to the ‘What did you see?’ field on the observation form. iNat will try to choose a single taxon based on this, but it may fail if it’s ambuguous

• taxon_id (int) – ID of the taxon to associate with this observation

• observed_on_string (Union[datetime.date, datetime.datetime, str]) – Date/time of the observation. Time zone will default to the user’s time zone if not specified.

• time_zone (str) – Time zone the observation was made in

• description (str) – Observation description

• tag_list (Union[str, List[str]]) – Comma-separated list of tags

• place_guess (str) – Name of the place where the observation was recorded. Note: iNat will not try to automatically look up coordinates based on this string

• latitude (float) – Latitude of the observation; presumed datum is WGS84

• longitude (float) – Longitude of the observation; presumed datum is WGS84

• map_scale (int) – Google Maps zoom level (from 0 to 19) at which to show this observation’s map marker.

• positional_accuracy (int) – Positional accuracy of the observation coordinates, in meters

• geoprivacy (str) – Geoprivacy for the observation

• observation_fields (Union[Dict, List[Dict]]) – Dict of observation fields in the format {id: value}. Alias for observation_field_values_attributes.

• flickr_photos (Union[int, List[int]]) – Flickr photo ID(s) to add as photos for this observation. User must have their Flickr and iNat accounts connected, and the user must own the photo(s) on Flickr.

• picasa_photos (Union[str, List[str]]) – Picasa photo ID(s) to add as photos for this observation. User must have their Picasa and iNat accounts connected, and the user must own the photo(s) on Picasa.

• facebook_photos (Union[str, List[str]]) – Facebook photo IDs to add as photos for this observation. User must have their Facebook and iNat accounts connected, and the user must own the photo on Facebook.

• local_photos (Iterable[Union[BinaryIO, str]]) – Image files, file-like objects, and/or paths for local photos to upload

• ignore_photos (bool) – If photos exist on the observation but are missing in the request, simply ignore them instead of deleting the missing observation photos

• user_agent (str) – A custom user-agent string to provide to the iNaturalist API

• observation_field_values_attributes (Union[Dict, List[Dict]]) –

Return type

List[Dict[str, Any]]

Returns

JSON response containing the newly updated observation(s)

Raises

requests.HTTPError – error 410 if the observation doesn’t exists or belongs to another user.