First of all: congratulations and thanks for this amazing API! Not sure if what I want makes sense but and I am contacting here but I don't think is the case o a feature request... Any way:

Is your feature request related to a problem? Please describe. I would like to download observations related to a project (get_observations(project_id=XXXX) from node_api) but I am a bit lost on mapping the results on DWC fields. I have saw that using rest_api is is possible to use request_format='dwc', but it is not possible to use project_id parameter.

Describe the solution you'd like Doesn't need to be a implementation, or a enhancement in the API. I am just wondering if there is any material with field matching between the get_observetions's results from node_api and DWC. Or any suggestion in this way.

Thanks in advance felipe

I think the docs would look a little nicer if we had a project logo. Of course this isn't a necessity, but I think it would be fun.

Python logo usage

I believe this is acceptable use of the python logo according to the Python Software Foundation's guidelines and trademark usage policy: specifically, it doesn't modify the shape of the logo, and isn't misleadingly applied to something that's not the python language. The guidelines do specifically say that modified colors ("derived logos") are allowed, and:

Use of derived logos for user groups and conferences... and freely distributed 3rd-party modules or tools -- Allowed if for the Python programming language.

iNaturalist logo usage

I believe this is also acceptable use of the iNat logo (from the press kit). From the FAQ:

Can I use the iNaturalist logo when linking to iNaturalist? Yes, with the caveat that its use in context should not imply endorsement by iNaturalist, the California Academy of Sciences, or National Geographic, and sale of items with the iNaturalist logo is not permitted. In general, if you're linking to iNaturalist because you're encouraging people to contribute to a project, are writing more generally about iNaturalist, or otherwise directing people to iNaturalist (e.g. via a flyer encouraging people to download the app and post while they visit a park), you can include the logo.

I'm fairly certain pyinaturalist meets these criteria. I would like to get confirmation from a staff member just to be sure, though. I also added a note to the Readme to clarify that this isn't an official project endorsed by iNaturalist.org. I don't think that would be a point of confusion, but you never know!

Ideas

~~Here are a few initial attempts:~~

Edit: Based on feeback from Cal Academy Legal, these aren't usable.

Add the /observations/observers endpoint from Node API.

My selfish motivation behind this: I'd like to be able to ask questions related to user engagement in a project, for instance "how many users have made 10+ observations in project X?," and this endpoint seems to be the place to do it.

It seems pretty straightforward and could be coupled with adding the /observations/identifiers endpoint as well.

• [x] /observations/observers
• [x] /observations/identifiers
• [x] Doctrings + type annotation
• [x] Usage examples
• [x] Sample response data
• [x] Unit tests

If you're ok with this, I'll start working on it over the next few weeks.

Is your feature request related to a problem? Please describe. I'd like to add sound files to observations, in the same way that is supported for photos

Describe the solution you'd like An analogue of add_photo_to_observation

The data models (#145) are mostly complete. The next step is to add support for API requests that return model objects instead of JSON. For backwards-compatibility, this should be an optional feature, not a replacement for the existing API functions.

Update: Decided to go with a compromise between options 2 and 3, described in comments below. This will involve an API client class and one controller class per resource type.

Options

There are at least two ways to go about this:

Option 1: Add a keyword arg to existing functions to specify return format

Example:

observations = get_observations(user_id='my_username', format='model')

Pros:

• This could work nicely with other possible return formats, if we add optional integration with pyinaturalist-convert later on. format could be used to specify any other supported format, for example format='csv'.
• No new functions for users to learn

Cons:

• Adding multiple return types for the same function generally isn't good practice
  • For other readers of client code that uses these functions, it can take a bit longer to understand what's going on
  • A long Union[x, y, z] isn't very useful as a return type annotation

Option 2: Add wrapper @classmethods to model objects

Example:

observations = Observation.search(user_id='my_username')

Pros:

• Results in more readable client code
• Makes a more obvious separation between the "low-level" API (raw JSON) and "high-level" API (model objects)

Cons:

• Mixes data with logic
  • It can be nice to keep those separate (as in MVC patterns), but not totally necessary
• Requires addling slightly more code to implement
  • This can be mitigated somewhat by using forge to reuse existing function signatures & docstrings

Examples in other API clients:

• Service resources in boto3, and other service-specific interfaces like S3.Bucket

Hi folks. I've been playing with pyinaturalist with the intention of using it to streamline the upload of a database of observation records and associated photographs.

However, I've run into a problem. The following works brilliantly:

response = create_observation(
    species_guess='Mallard',
    observed_on_string='2020-05-03',
    time_zone='Brussels',
    description='Test observation, will be deleted shortly',
    tag_list='test, API',
    latitude=-53.186881, 
    longitude=-134.823015,
    positional_accuracy=50, # GPS accuracy in meters
    access_token=token,
)

new_observation_id = response[0]['id']

add_photo_to_observation(
    new_observation_id,
    access_token=token,
    photo='H:\My Documents\iNaturalist\inaturalistTest3.jpg',
)

However, when I try to combine it all into a single step using the local_photos parameter I get an error:

response = create_observation(
    species_guess='Mallard',
    observed_on_string='2020-05-03',
    time_zone='Brussels',
    description='Test observation, will be deleted shortly',
    tag_list='test, API',
    latitude=-53.186881, 
    longitude=-134.823015,
    positional_accuracy=50, # GPS accuracy in meters
    access_token=token,
    local_photos='H:\My Documents\iNaturalist\inaturalistTest3.jpg',
)

TypeError: Object of type BytesIO is not JSON serializable

Unfortunately, I'm not yet competent enough with python to know whether this is a problem on my end, or if it's an issue deeper in the package. In either case, your advice and guidance would be much appreciated.

Describe the bug I'm using observed_on_string but the value entered does not appear on the record once uploaded

To Reproduce

# Getting started
install.packages('reticulate')
library(reticulate)

# This will tell you where your python is
# If you dont have python you will need to install it
Sys.which("python") 

# Install the iNat python package https://pypi.org/project/pyinaturalist/
py_install("pyinaturalist==0.14.0dev356", pip = TRUE)

# Create an app on iNat here: https://www.inaturalist.org/oauth/applications/new
# save out id and secret to an object and dont share with others
load('token.rdata')

# Start using the package
pynat <- import('pyinaturalist')

# get token
token <- pynat$get_access_token(token[[1]],
                                token[[2]],
                                token[[3]],
                                token[[4]])

# Submit an observation
response <- pynat$create_observation(
  species_guess = 'daubentons bat',
  observed_on_string = '2021-05-02',
  description='This is a bat auto upload',
  latitude = 51.599840854449226, 
  longitude = -1.130838820690541,
  positional_accuracy = 23, # GPS accuracy in meters
  access_token = token
)

Feature description

In some case observation can have obscured coordinates (for ex. when the species is endangered). It would be nice to still be able to fetch all remaining information except the precise geolocation, without authenticating.

Use case

I need to fetch all observation from a project but I can't because some have their geolocation obscured by iNaturalist. Only "The person who made the observation, Individuals who the observer has trusted with their hidden coordinates and Curators of the projects" can fetch it.

Workarounds

• Logging at iNaturalist and use the https://www.inaturalist.org/observations/export functions.
• Authenticating https://pyinaturalist.readthedocs.io/en/stable/user_guide.html#authentication (didn't try at the moment because I didn't fulfil the requirements to build an app see screenshot)

Hello,

Thank you for the work done, is really useful. I would like to know how can I get all the projects information, Is it possible?

Thank you in advance, Miriam

Is your feature request related to a problem? Please describe. I have succesfully installed the package. I have tested some of the examples, like get_observations() (which worked perfectly)

But I want to upload my observations and I couldn't make authentication work:

# this worked perfectly:
observations = get_observations(user_id='myuserid')
for obs in observations['results']:
    print(format_observations(obs))

# this was filled in with real values, but didn't work:
token = get_access_token(
    username='my_username',
    password='my_password',
    app_id='my_app_id',
    app_secret='my_app_secret',
)

I don't post the rest of code because I already got an error here:

Traceback (most recent call last):
  File "pyinat.py", line 25, in <module>
    token = get_access_token(
  File "C:\...\Python38\lib\site-packages\pyinaturalist\auth.py", line 80, in get_access_token
    response.raise_for_status()
  File "C:\...\Python38\lib\site-packages\requests\models.py", line 943, in raise_for_status
    raise HTTPError(http_error_msg, response=self)
requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: https://www.inaturalist.org/oauth/token

Describe the solution you'd like I would like to have bit more explained example of the first two get_access_token() parameters:

• Is 'username' the email used to login inaturalist website? (i.e. '[email protected]') Or is it, like in get_observations(user_id), the user shown in the inaturalist user page url? (i.e. 'niconoe'). I tried both, but no luck.
• Is 'password' the one used for inaturalist web login? (it looks odd to me providing it to an application, but I did it)

I would also like to have some hints about how to create the inaturalist application required to login using pyinaturalist:

• When creating the inaturalist application, do we actually need to have a real web server Callback url, or is it something optional just in case we want to control our application usage? Or perhaps we have to fill in pyinaturalist github url here?
• Some question for the Url outside inaturalist field. Is this just optional?

Describe alternatives you've considered I wonder if it takes a while for the app to be aproved by inaturalist. But I don't think that's the problem because the interface says nothing about that

Thanks a lot in advance

Hey @niconoe, one more thing I forgot to ask about: could you add a webhook to this repo for me so I can sync issues with GitKraken Boards? It should just take a couple minutes to set up.

Now that I have a larger number of small projects, I wanted to be able to see all my issues in one place. GitHub Projects can do this, but requires transferring repos to a single owner or organization. It looks like GitKraken Boards can do this by just adding an OAuth application and webhooks.

Steps

1. Make an account and give it access to the pyinaturalist repo.

2. Go to 'Create a synced board' in the lower left and add pyinaturalist:

3. Go to ⚙️-> Users in the upper right and add me to the board:

Back on the GitHub repo, you should then see at least one webhook for GitKraken under Settings -> Webhooks. You can remove those if you ever need to revoke access for some reason in he future.

Also let me know if you have any alternative suggestions for a free Kanban-style board that can sync with GitHub issues and PRs. Thanks!

Bumps rich from 12.6.0 to 13.0.0.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Bumps pre-commit from 2.20.0 to 2.21.0.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Bumps keyring from 23.11.0 to 23.13.1.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Bumps furo from 2022.9.29 to 2022.12.7.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

The problem

When a taxon is reloaded to fetch its full record, if all names were originally requested, they won't be included on the taxon object after the reload.

Expected behavior

If I fetch a taxon via client.taxa.autocomplete() and then reload it with taxon.load_full_record(), I expect all_names=True passed on the original autocomplete request to be applied to the load_full_record request, and consequently taxon.names should contain all names, as requested. Instead, taxon.names is empty.

Steps to reproduce the behavior

>>> client = iNatClient()
>>> taxon = client.taxa.autocomplete(q='Picoides pubescens', all_names=True).one()
>>> taxon.names
[
    {'is_valid': True, 'name': 'Dryobates pubescens', 'position': 0, 'locale': 'sci'},
    {'is_valid': True, 'name': 'Downy Woodpecker', 'position': 0, 'locale': 'en'},
    {'is_valid': True, 'name': 'Dunspett', 'position': 1, 'locale': 'sv'},
    {'is_valid': True, 'name': 'Donsspecht', 'position': 2, 'locale': 'nl'},
    {'is_valid': True, 'name': 'Dværgflagspætte', 'position': 3, 'locale': 'da'},
    {'is_valid': True, 'name': 'DOWO', 'position': 4, 'locale': 'und'},
    {'is_valid': True, 'name': 'Пушистый дятел', 'position': 8, 'locale': 'ru'},
    {'is_valid': True, 'name': 'Pica-pau-felpudo', 'position': 9, 'locale': 'pt'},
    {'is_valid': True, 'name': 'Carpintero velloso-menor', 'position': 12, 'locale': 'es'},
    {'is_valid': True, 'name': 'pic mineur', 'position': 13, 'locale': 'fr'},
    {'is_valid': True, 'name': 'Carpintero Albinegro Menor', 'position': 14, 'locale': 'es'},
    {'is_valid': True, 'name': 'Dunenspecht', 'position': 15, 'locale': 'de'},
    {'is_valid': True, 'name': 'keijutikka', 'position': 16, 'locale': 'fi'},
    {'is_valid': True, 'name': 'strakapoud osikový', 'position': 17, 'locale': 'cs'},
    {'is_valid': True, 'name': 'セジロコゲラ', 'position': 17, 'locale': 'ja'},
    {'is_valid': True, 'name': 'ďateľ ozdobný', 'position': 19, 'locale': 'sk'},
    {'is_valid': True, 'name': 'picchio lanuginoso', 'position': 20, 'locale': 'it'},
    {'is_valid': True, 'name': '绒啄木鸟', 'position': 21, 'locale': 'zh-CN'},
    {'is_valid': True, 'name': 'Dzięcioł kosmaty', 'position': 22, 'locale': 'pl'},
    {'is_valid': True, 'name': '絨啄木鳥', 'position': 23, 'locale': 'zh'},
    {'is_valid': True, 'name': 'Dunspett', 'position': 24, 'locale': 'nb'},
    {'is_valid': True, 'name': 'Дятел пухнастий', 'position': 25, 'locale': 'uk'},
    {'is_valid': False, 'name': 'Picoides pubescens', 'position': 5, 'locale': 'sci'},
    {'is_valid': False, 'name': 'Dendrocopos pubescens', 'position': 6, 'locale': 'sci'},
    {'is_valid': False, 'name': 'Dendrocopus pubescens', 'position': 7, 'locale': 'sci'},
    {'is_valid': False, 'name': 'Baapaase', 'position': 18, 'locale': 'oj'}
]
>>> taxon.load_full_record()
>>> taxon.names
[]
>>> 

Workarounds

Either of these will do:

1. Save the taxon.names before doing the taxon.load_full_record()

OR

2. Don't use taxon.load_full_record(). Instead, perform a client.taxa(taxon.id, all_names=True) to fetch the record with all names (my current workaround, but then I need to separately save anything from the original request that I need later, like taxon.matched_term).

Environment

• OS & version: Debian 10
• Python version: 3.9
• Pyinaturalist version or branch: main branch

Feature description

Please provide the same conservation status code to status name mapping in the ConservationStatus model for the full taxon record as iNaturalist itself provides in other endpoints (e.g. autocomplete & observations).

Use case

The use case is to show a taxon's local conservation status using the same name that a user is familiar with when they have specified their preferred place. For background, see this discussion on the iNaturalist forums: https://forum.inaturalist.org/t/establishment-means-in-two-v1-taxa-endpoints-either-not-complete-or-not-consistent/15099

In that discussion, Kenichi suggested I should map the iucn code using a local table on the client side. For background (since the link to github that he gave no longer works), please see the inaturalist code here (this time using stable URLs):

First, the iucn code to name mapping:

https://github.com/inaturalist/inaturalist/blob/77f6bac2b25c1bf431395e5142bf8580722ecaf8/app/models/taxon.rb#L349-L389

And then the authority-specific mappings:

https://github.com/inaturalist/inaturalist/blob/039de2bc5fe2b5e6aefba0a5f057218f64199c24/app/models/conservation_status.rb#L42-L105

So, for example, suppose a user's preferred place is Nova Scotia and the taxon they would like to look up is Cathartes aura (Turkey Vulture). To fully comprehend its status, they should be presented with the status name, the code, the place name for the status, and a link to the listed taxa record on the web where they can learn more:

Most of this info can be obtained from the full taxon record with client.taxa(4756, preferred_place_id=6853), but not the status name itself. If the ConservationStatus model provided this mapping via a local table lookup as Kenichi suggested, then the user would not have to worry about which API call the model was created from, or have to do a wasteful extra API call to obtain it.

Workarounds

Lookup the taxon using the /v1/taxa/autocomplete endpoint which sets the taxon.conservation_status.status_name to the expected value. For example, https://api.inaturalist.org/v1/taxa/autocomplete?q=turkey+vulture&preferred_place_id=6853 returns status_name: "imperiled".

Note: if taxon.load_full_record() is called after this, the status_name is not returned, i.e. it will "walk" on the value that we just had before the call. I was originally going to ask for a workaround in pyinat wherein this field value is kept, but that's not a complete solution, and using a code-to-name mapping in the client seems better.