Observations

pyinaturalist.v0.observations.create_observation(**params)#

Create a new observation

Notes

Requires authentication
API reference: POST /observations

Parameters:

access_token (Optional[str]) – An access token for user authentication, as returned by get_access_token()
species_guess (Optional[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 ambiguous
taxon_id (Optional[int]) – ID of the taxon to associate with this observation
observed_on (Union[date, datetime, str, None]) – Alias for observed_on_string; accepts datetime objects.
observed_on_string (Union[date, datetime, str, None]) – Date/time of the observation. Time zone will default to the user’s time zone if not specified.
time_zone (Optional[str]) – Time zone the observation was made in
description (Optional[str]) – Observation description
tag_list (Union[str, Iterable[str], None]) – Comma-separated list of tags
place_guess (Optional[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 (Optional[float]) – Latitude of the observation; presumed datum is WGS84
longitude (Optional[float]) – Longitude of the observation; presumed datum is WGS84
map_scale (Optional[int]) – Google Maps zoom level (from 0 to 19) at which to show this observation’s map marker.
positional_accuracy (Optional[int]) – Positional accuracy of the observation coordinates, in meters
geoprivacy (Optional[str]) – Geoprivacy for the observation
observation_fields (Union[Dict, List[Dict], None]) – Dict of observation fields in the format {id: value}. Alias for observation_field_values_attributes.
flickr_photos (Union[int, Iterable[int], None]) – 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, Iterable[str], None]) – 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, Iterable[str], None]) – 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.
photos (Union[BinaryIO, str, Iterable[Union[BinaryIO, str]], None]) – One or more image files, file-like objects, file paths, or URLs
sounds (Union[BinaryIO, str, Iterable[Union[BinaryIO, str]], None]) – One or more sound files, file-like objects, file paths, or URLs
photo_ids (Union[int, Iterable[int], str, Iterable[str], None]) – One or more IDs of previously uploaded photos to attach to the observation
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

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

Return type:

List[Dict[str, Any]]

Returns:

JSON response containing the newly created observation(s)

Raises:

HTTPError – If the call is not successful
Note – The exception’s response attribute gives more details about the errors.

pyinaturalist.v0.observations.delete_observation(observation_id, **params)#

Delete an observation

Notes

Requires authentication
API reference: DELETE /observations/{id}

Parameters:

observation_id (int) – iNaturalist observation ID
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

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

Returns:

If successful, no response is returned from this endpoint

Raises:

.ObservationNotFound – if the requested observation doesn’t exist
HTTPError – 403 if the observation belongs to another user

pyinaturalist.v0.observations.get_observations(**params)#

Get observation data, optionally in an alternative format

Notes

API reference: GET /observations

Parameters:

q (Optional[str]) – Search observation properties
d1 (Union[date, datetime, str, None]) – Must be observed on or after this date
d2 (Union[date, datetime, str, None]) – Must be observed on or before this date
day (Union[int, Iterable[int], None]) – Must be observed within this day of the month
month (Union[int, Iterable[int], None]) – Must be observed within this month
year (Union[int, Iterable[int], None]) – Must be observed within this year
license (Union[str, Iterable[str], None]) – Observation must have this license
photo_license (Union[str, Iterable[str], None]) – Must have at least one photo with this license
out_of_range (Optional[bool]) – Observations whose taxa are outside their known ranges
list_id (Optional[int]) – Taxon must be in the list with this ID
quality_grade (Optional[str]) – Must have this quality grade
id (Union[int, Iterable[int], None]) – Must have this observation ID
taxon_id (Union[int, Iterable[int], None]) – Only show observations of these taxa and their descendants
taxon_name (Union[str, Iterable[str], None]) – Taxon must have a scientific or common name matching this string
iconic_taxa (Union[str, Iterable[str], None]) – Taxon must by within this iconic taxon
updated_since (Union[datetime, str, None]) – Must be updated since this time
has (Union[str, Iterable[str], None]) – Catch-all for some boolean selectors. This can be used multiple times, e.g. has=['photos', 'geo']
m1 (Union[date, datetime, str, None]) – First month of a month range
m2 (Union[date, datetime, str, None]) – Last month of a month range
h1 (Union[date, datetime, str, None]) – First hour of an hour range
h2 (Union[date, datetime, str, None]) – Last hour of an hour range
on (Union[date, datetime, str, None]) – Filter by date string
extra (Optional[str]) – Retrieve additional information. ‘projects’ returns info about the projects the observations have been added to, ‘observation_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 (Optional[float]) – NE latitude of bounding box
nelng (Optional[float]) – NE longitude of bounding box
swlat (Optional[float]) – SW latitude of bounding box
swlng (Optional[float]) – SW longitude of bounding box
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_observations(id=45414404, converters='atom')

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

Return type:: Union[List, str]
Returns:: Return type will be dict for the json response format, and str for all others.

pyinaturalist.v0.observations.update_observation(observation_id, **params)#

Update a single observation

Notes

Requires authentication
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.

Parameters:

observation_id (int) – iNaturalist observation ID
access_token (Optional[str]) – An access token for user authentication, as returned by get_access_token()
species_guess (Optional[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 ambiguous
taxon_id (Optional[int]) – ID of the taxon to associate with this observation
observed_on (Union[date, datetime, str, None]) – Alias for observed_on_string; accepts datetime objects.
observed_on_string (Union[date, datetime, str, None]) – Date/time of the observation. Time zone will default to the user’s time zone if not specified.
time_zone (Optional[str]) – Time zone the observation was made in
description (Optional[str]) – Observation description
tag_list (Union[str, Iterable[str], None]) – Comma-separated list of tags
place_guess (Optional[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 (Optional[float]) – Latitude of the observation; presumed datum is WGS84
longitude (Optional[float]) – Longitude of the observation; presumed datum is WGS84
map_scale (Optional[int]) – Google Maps zoom level (from 0 to 19) at which to show this observation’s map marker.
positional_accuracy (Optional[int]) – Positional accuracy of the observation coordinates, in meters
geoprivacy (Optional[str]) – Geoprivacy for the observation
observation_fields (Union[Dict, List[Dict], None]) – Dict of observation fields in the format {id: value}. Alias for observation_field_values_attributes.
flickr_photos (Union[int, Iterable[int], None]) – 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, Iterable[str], None]) – 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, Iterable[str], None]) – 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.
photos (Union[BinaryIO, str, Iterable[Union[BinaryIO, str]], None]) – One or more image files, file-like objects, file paths, or URLs
sounds (Union[BinaryIO, str, Iterable[Union[BinaryIO, str]], None]) – One or more sound files, file-like objects, file paths, or URLs
photo_ids (Union[int, Iterable[int], str, Iterable[str], None]) – One or more IDs of previously uploaded photos to attach to the observation
ignore_photos (bool) – If photos exist on the observation but are missing in the request, ignore them instead of deleting the missing observation photos
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

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

Return type:

List[Dict[str, Any]]

Returns:

JSON response containing the newly updated observation

Raises:

HTTPError – if the call is not successful.
Note – iNaturalist returns an error 410 if the observation doesn’t exists or belongs to another user.

pyinaturalist.v0.observations.upload_photos(observation_id, photos, **params)#

Upload a local photo and assign it to an existing observation

Notes

Requires authentication
API reference: POST /observation_photos

Example

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

Multiple photos can be uploaded at once:

>>> upload_photos(
>>>     1234,
>>>     ['~/observations/2020_09_01_14003156.jpg', '~/observations/2020_09_01_14004223.jpg'],
>>>     access_token=token,
>>> )

Parameters:

observation_id (int) – the ID of the observation
photo – An image file, file-like object, or path
access_token – Access token for user authentication, as returned by get_access_token()

Return type:

List[Dict[str, Any]]

Returns:

Information about the uploaded photo(s)

pyinaturalist.v0.observations.upload_sounds(observation_id, sounds, **params)#

Upload a local sound file and assign it to an existing observation

Notes

Requires authentication

Example

>>> token = get_access_token()
>>> upload_sounds(1234, '~/observations/2020_09_01_14003156.mp3', access_token=token)

Multiple sounds can be uploaded at once:

>>> upload_sounds(
>>>     1234,
>>>     ['~/observations/2020_09_01_14003156.mp3', '~/observations/2020_09_01_14004223.wav'],
>>>     access_token=token,
>>> )

Parameters:

observation_id (int) – the ID of the observation
sound – An audio file, file-like object, or path
access_token – Access token for user authentication, as returned by get_access_token()

Return type:

List[Dict[str, Any]]

Returns:

Information about the uploaded sound(s)

Observations#

Summary#

Module Contents#

`create_observation`(**params)	Create a new observation
`delete_observation`(observation_id, **params)	Delete an observation
`get_observations`(**params)	Get observation data, optionally in an alternative format
`update_observation`(observation_id, **params)	Update a single observation
`upload_photos`(observation_id, photos, **params)	Upload a local photo and assign it to an existing observation
`upload_sounds`(observation_id, sounds, **params)	Upload a local sound file and assign it to an existing observation