I just noticed while playing with the new taxa endpoints that boolean API parameters need to be expressed as JS strings, for example:

get_taxa(q='Lixus bardanae', is_active='false')

It would be better to be able to do:

get_taxa(q='Lixus bardanae', is_active=False)

To do:

• investigate if we have a handy (lightweight, applicable to other endpoints, ...) solution for this
• if yes, fix
• if no, properly document this behaviour
• see if the issue is also present with other functions/endpoints

Currently the same JSON files are used for testing and for example responses in the docs. Since there are differences (type conversions, etc.), a separate set of modified responses should be made for documentation purposes.

For the docs, some of the more verbose response fields (like geometry GeoJSON, extra levels of nested taxa/observation data, etc.) could be truncated to make it easier to read.

Publishing pre-release builds from the dev branch would be useful, to make it easier to use the latest pyinaturalist changes in a client application. This also helps to discover any build-related issues early on, before merging to master.

Per PEP 440, an artifact with a version suffix like 0.10.dev5 indicates that it's a pre-release; it can be hosted by pypi, ignored by pip install, and only installed with either pip install --pre or the specific version (pip install pyinaturalist==0.10.dev5).

I've done this in other CI systems, and I'm not sure yet how to do this with Travis CI, but it would be worth exploring.

Add the three GET Messages endpoints from the Node (v1) API.

• /messages
• /messages/{id}
• /messages/unread
• Doctrings + type annotations
• Usage examples
• Sample response data
• Unit tests

The following functions have file parameters:

• rest_api.create_observations()
• rest_api.add_photo_to_observation()

I'd like to be able to pass either file paths, files, or file-like objects to these, e.g.:

# File path
rest_api.add_photo_to_observation(1234, '~/Photos/obs_1234.jpg', access_token)

# File object (current behavior)
with open('~/Photos/obs_1234.jpg', 'rb') as f:
    rest_api.add_photo_to_observation(1234, f, access_token)

# File-like object
base64_photo_bytes = BytesIO(b'...')
rest_api.add_photo_to_observation(1234, base64_photo_bytes, access_token)

This should be straightforward to add, preferably with a reusable utility function.

Sume functions already have this, but I think it will be useful to make all the function signatures consistent, and add annotated request params for the endpoints that don't have them yet. This is mainly to make them easier to use within an IDE without referring to the API docs, and to provide better runtime errors if an invalid parameter is passed.

This will just replace the keyword args **params for some functions. To avoid breaking backwards-compatibility, the remaining functions with the positional arg params (like get_observations()) will accept both, show a DeprecationWarning if called with params=<dict> (but otherwise still work as it did previously), and later remove params in some future release. For example:

def get_observations(
	params: Dict = None, 
	acc: bool = None,
	captive: bool = None,
	endemic: bool = None,
	geo: bool = None,
	...,
	user_agent: str = None,
) -> Dict[str, Any]:
    if params:
        warnings.warn(DeprecationWarning("The 'params' argument is deprecated; please use keyword arguments instead"))

Endpoints to update

• node_api.get_observations() (Note: This has 77 parameters! Yikes!)
• node_api.get_observation_species_counts()
• node_api.get_all_observations()
• node_api.get_taxa()
• node_api.get_taxa_autocomplete()
• rest_api.get_observations()
• rest_api.create_observations()
• rest_api.update_observation()

I just realized that observation timestamps (observed_on_string) aren't in a consistent format. This field may come directly from user-submitted photo metadata. The main issue here is timezone offset.

Some timestamps declare this explicitly, for example: 'Sat Sep 26 2020 12:09:51 GMT-0700 (PDT)'
While others only have the timezone code: '2020-09-27 9:20:02 AM PDT'
python-dateutil is able to handle most other variations, but can't automatically convert a timezone code to a timezone offset.

Because of this, I think it would be useful to handle this in pyinaturalist observation endpoints and any other endpoints that return timestamps. Otherwise, any client code that wants to make use of observation time information would have to handle this. There is a separate time_zone_offset field that contains an offset string like '-08:00', which could be parsed and added to a timezone-unaware datetime object.

• Parse timestamps
• Parse and apply timezone offsets
• Convert observation created_at
• Convert observation observed_on
• Convert observation field created_at
• Convert observation field observed_on
• Convert project created_at
• Convert project updated_at
• Convert taxon created_at
• Convert taxon updated_at
• Unit tests

Especially useful to test code that does some "write" operations.

The idea is that in test mode, the API calls are not performed but logged somewhere (to be defined).

Original photo EXIF, XMP, and/or IPTC metadata is currently not available in the API. It is, however, available in the web UI (example), so it's potentially scrapable.
Note: It appears that photo metadata is only visible when you are logged in, so user authentication will be required.

Relevant discussion:

• https://forum.inaturalist.org/t/api-to-retrieve-photo-metadata/15616/2
• inaturalist/iNaturalistAPI#188

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

A choropleth map of observations would be a great example to add. This can be just for a single country for now, preferably at the county (or equivalent) level.

Example: https://altair-viz.github.io/gallery/choropleth.html

Ideally this would use standardized place IDs (like FIPS codes in the United States) instead of iNat place IDs, to make it easier to combine this with other geospatial datasets. Plan B would be to just use iNat place IDs and polygons.

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.

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

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

It will be useful to have templates for:

• Bug reports
• Feature requests
• New endpoint requests
• New endpoint PRs

After mail exchanges with an user of the library, it appear it would be nice to add access to the computer vision (species suggestion based on a picture) to pyinaturalist.

After having a look at the source code and what the webapp does, we discovered two undocumented endpoints in the Node API:

https://github.com/inaturalist/iNaturalistAPI/blob/5b3b6d4a588f5bf68259467fc37809f6aa2371ac/lib/inaturalist_api.js#L268-L276

• score_observation is used by the webapp when asking suggestions for an already existing observation.
• I guess score_image is even more interesting and allows to score an uploaded images, without needing an iNaturalist observation. No clue of how to use it (image upload), so we have to experiment a bit.

Is the fact that's it is currently undocumented an issue? I can imagine iNat team does not want its servers flooded by people who have no interest in the project... (but pyinaturalist is probably obscure enough to avoid this). Also, maybe this API is considered semi-private and therefore change frequently?

Hey @JWCook!

Since you made great contributions to this project and that it's unfortunately difficult for me at the moment to properly follow: would you be interested in becoming its official maintainer?

This might be simple, and if so, sorry for adding to the clutter.

I need to use a custom certificate in my calls. For example, here's the result using your very first demo:

from pyinaturalist.node_api import get_all_observations

obs = get_all_observations(params={'user_id': 'tghoward'})
Traceback (most recent call last):

  File "<ipython-input-18-33257754f514>", line 1, in <module>
    obs = get_all_observations(params={'user_id': 'tghoward'})

  File "C:\Users\tghoward\AppData\Local\ESRI\conda\envs\arcpro_tim\lib\site-packages\pyinaturalist\node_api.py", line 80, in get_all_observations
    page_obs = get_observations(params=iteration_params, user_agent=user_agent)

  File "C:\Users\tghoward\AppData\Local\ESRI\conda\envs\arcpro_tim\lib\site-packages\pyinaturalist\node_api.py", line 53, in get_observations
    r = make_inaturalist_api_get_call('observations', params=params, user_agent=user_agent)

  File "C:\Users\tghoward\AppData\Local\ESRI\conda\envs\arcpro_tim\lib\site-packages\pyinaturalist\node_api.py", line 26, in make_inaturalist_api_get_call
    response = requests.get(urljoin(INAT_NODE_API_BASE_URL, endpoint), params, headers=headers, **kwargs)

  File "C:\Users\tghoward\AppData\Local\ESRI\conda\envs\arcpro_tim\lib\site-packages\requests\api.py", line 75, in get
    return request('get', url, params=params, **kwargs)

  File "C:\Users\tghoward\AppData\Local\ESRI\conda\envs\arcpro_tim\lib\site-packages\requests\api.py", line 60, in request
    return session.request(method=method, url=url, **kwargs)

  File "C:\Users\tghoward\AppData\Local\ESRI\conda\envs\arcpro_tim\lib\site-packages\requests\sessions.py", line 533, in request
    resp = self.send(prep, **send_kwargs)

  File "C:\Users\tghoward\AppData\Local\ESRI\conda\envs\arcpro_tim\lib\site-packages\requests\sessions.py", line 646, in send
    r = adapter.send(request, **kwargs)

  File "C:\Users\tghoward\AppData\Local\ESRI\conda\envs\arcpro_tim\lib\site-packages\requests\adapters.py", line 514, in send
    raise SSLError(e, request=request)

SSLError: HTTPSConnectionPool(host='api.inaturalist.org', port=443): Max retries exceeded with url: /v1/observations?user_id=tghoward&order_by=id&order=asc&per_page=30&id_above=0 (Caused by SSLError(SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",),))

I notice you are using the requests library and a little sleuthing led me to successful connection using requests directly:

import requests
verify="D:/ca-bundle.crt"
response = requests.get('https://www.inaturalist.org/observations/30723019.json', verify=verify)

the object response has the data I requested.

My question: how can define the correct certificate in my get_all_observations call?

thanks in advance.

Follow-up to issue #68.

There is a convenient cross-platform keyring package that provides integration with the system keyring. This would be useful to have as an optional method of authentication, and would definitely be my preference to use, if it were available.

It's been used on projects by my team at work, and it works fairly well. Keyring backends supported:

• macOS Key chain
• Freedesktop Secret Service (on Gnome, Xfce, etc.)
• KDE4 & KDE5 KWallet (requires dbus)
• Windows Credential Locker

This could probably be added as an optional dependency. The order of precedence, then, would be:

1. get_access_token() arguments
2. Environment variables
3. Keyring (if keyring is installed)
4. If none of the above were found, raise an exception

Follow-up from PR #55 .

Example traceback:

  File "/home/cookjo/workspace/pyinaturalist/pyinaturalist/rest_api.py", line 70, in <module>
    def get_observations(user_agent: str = None, **kwargs) -> Union[List, str]:
  File "/home/cookjo/workspace/pyinaturalist/pyinaturalist/forge_utils.py", line 59, in f
    func = copy_signatures(func, template_functions)
  File "/home/cookjo/workspace/pyinaturalist/pyinaturalist/forge_utils.py", line 121, in copy_signatures
    return revision(target_function)
ValueError: Received multiple parameters with name 'user_agent'
]

The GET /observations/species_counts
endpoint returns counts of observations of all species matching the given search parameters. This is useful, for example, for getting all the species that a user has observed, ordered by number of observations.

This will also be a good opportunity to add some more request parameter validation. Several observation request parameters are restricted to a list of possible choices; for example, iconic taxa, license, and geoprivacy. If we explicitly define these choices and validate params before sending the API request (with clear error messages for validation errors), it will make it easier to debug bad requests in client applications. Otherwise these inputs would return a 400 response with potentially less helpful/predictable error messages.

Main Tasks

• Endpoints
  • /observations/species_counts
  • Parameter validation for all multiple-choice request params
• Docs
  • Doctrings + type annotations
  • Usage examples
  • Update release notes
• Tests
  • Sample response data
  • Unit tests for new endpoint
  • Unit tests for additional utility functions

Sphinx-apidoc is a useful tool to take autodoc a step further and to generate Sphinx source files, so you don't have to remember to make a .rst file for every one of your modules. This is easy to do in a Makefile or other script; the only catch is that readthedocs uses its own builder, and doesn't use the Makefile.

Fortunately, others have wanted to do the same thing, and sphinxcontrib-apidoc exists for that purpose. The same method used by that extension (adding hooks into Sphinx builder events) can be used to add any other custom behavior that would otherwise go into the Makefile. This has the added benefit of making those steps just work cross-platform, without the need for a separate Makefile and make.bat.

Hi - I'm an iNat DevOps engineer. I don't have experience with pyinaturalist as a user, but I do see the requesting coming in. We seem to be getting more requests with user agent python-requests/2.20.0. I'm wondering if it's possible for users to set a custom user agent, and if so could that be added as a recommended best practice? Ideally the user agent would indicate they are using pyinaturalist, and it would include their iNaturalist login, or their email, or their project name. That way people acting in good faith don't get mixed up with the scrapers, who we may ban for making excessive number of API calls. Thanks for considering!

Hello! I am Jacob from the U.S. If you look at my profile you'll see that my colleague and I are working on some applications for collectors (mostly students and researchers). We were looking into consuming the iNaturalist API to add send our observations there as well as our other destination. I stumbled upon your project and I thought it might be a good idea to reach out and get an idea of what your plans are, such as, do you plan to add the module to PyPi eventually? We may like to help you out!

Greetings from across the pond,
Jacob

For example, currently client code can receive something like {'error': 'Cette observation n’existe plus.'}. as a return value from update_observation()...

So the client code should look for an 'error' key in each of the results (and I'm not sure the API is really consistent in that). So it seems it would be more pythonic and nicer to raise an exception (a very specific if possible, or general one like Error 500 otherwise) each time it's not Status=200.

Currently, put_observation_field_values() will fail if the specified observation field value already exists. It would be much more convenient to create if it doesn't exist, and update (delete and recreate) otherwise. I see this was already noted in the TODOs.

• Make the doc basics and make it build locally
• Configure/publish on ReadTheDocs
• Set up GitHub hooks for automatic buils (needs permission to do so)
• Make an API page (set type annotations and try to use them with autodoc?)
• Install page: show how to install master from GitHub
• Add a "release page" with complete release instructions (for future me)

Add the two basic GET Users endpoints from the Node (v1) API.

• /users/{id}
• /users/autocomplete
• Doctrings + type annotations
• Usage examples
• Sample response data
• Unit tests

Datetime format issue

After looking into other API request parameter types for Issue #17, I think dates and datetimes could benefit from some additional conversion or at least sanity checks. I'm not sure how many formats work, but from a couple quick tests it looks like both the Node API and REST API at least accept ISO 8601 format optionally with time zone (2020-05-06T0243:09.333876-05:00).

When an unsupported date format is provided, though, the API will ignore the param and quietly return incorrect results. So in get_observations(), for example, the params created_d1 and created_d2 currently work fine if you provide strings in the correct format, but will provide unexpected results (e.g., 200 response w/ results but no time constraints) if not. For example:

# Unrecognized format; results not filtered by created date
>>>  r = get_observations({'id': 45210532, 'created_d1': '20200508194556'}); len(r['results'])
1
# Recognized format; results correctly filtered by created date
>>> r = get_observations({'id': 45210532, 'created_d1': '2020-05-08T19:45:56'}); len(r['results'])
0

A convenient addition to that would be the ability to accept either:

1. A datetime object
2. A datetime string in any format recognized by dateutil

And then convert to ISO 8601 and add local timezone info (±xx:xx) before sending the request. Let me know if that sounds good to you, or if you have other ideas on how to handle that.

Timezone Issue

This is pretty minor and most people probably wouldn't even notice, but searches on datetime parameters are not accurate down to the hour. If timezone info isn't provided, the API assumes UTC time. For example, take this observation created on 2020-05-07T23:57:29 SAST (UTC+2):

# No results, because API assumes UTC
>>> r = get_observations({'id': 45210532, 'created_d1': '2020-05-07T23:00:00'}); len(r['results'])
0
# Returns the expected result when either timezone offset is specified or UTC time is specified with no offset
>>>  r = get_observations({'id': 45210532, 'created_d1': '2020-05-07T23:00:00+02:00'}); len(r['results'])
1
>>>  r = get_observations({'id': 45210532, 'created_d1': '2020-05-07T21:00:00'}); len(r['results'])
1

Fortunately, adding timezone info from local system time is an easy fix.

• Test & document unknown/undefined behavior noted in TODOs for create_observations()
• Test & document unknown/undefined behavior noted in TODOs for update_observations()
• Test & document unknown/undefined behavior noted in TODOs for delete_observations()
• Simplify usage of observation_field_values_attributes for create and update; support a flat dict instead of nested list of dicts
• Implement local_photos for create and update, and support either local file path(s) or object(s)
  • Moved to #57
• Update add_photo_to_observation() with support for local_photos

Use mock objects so our tests don't rely on an external API?

I'd like to add the two Controlled Terms from the Node API.

• /controlled_terms
• /controlled_terms/for_taxon
• Doctrings + type annotation
• Error handling
• Usage examples
• Sample response data
• Unit tests

Note: /controlled_terms/for_taxon appears to return a 422 if the specified taxon does not exist, which is odd; 404 would seem more appropriate. This should be wrapped in a custom exception; see #49

The nbsphinx extension can be used for this. As a nice but optional addition, it may also be possible to generate a gallery of thumbnails from notebook output images using aphinx-gallery.

API docs: https://api.inaturalist.org/v1/docs/#!/Observations/get_observations_histogram

This is a useful endpoint that returns different response formats depending on the time interval specified (year, month, week, day, hour, month of year, week of year). Month of year and week of year return integer keys (as strings, since it's JSON); the others return timestamps.

Example response for 'month of year' (default):

{
  "total_results": 12,
  "page": 1,
  "per_page": 12,
  "results": {
    "month_of_year": {
      "1": 272,
      "2": 253,
      "3": 992,
      "4": 3925,
      "5": 7983,
      "6": 7079,
      "7": 9150,
      "8": 8895,
      "9": 8374,
      "10": 6060,
      "11": 920,
      "12": 382
    }
  }
}

Example response for 'month':

{
  "total_results": 13,
  "page": 1,
  "per_page": 13,
  "results": {
    "month": {
      "2020-01-01": 271,
      "2020-02-01": 253,
      "2020-03-01": 992,
      "2020-04-01": 3925,
      "2020-05-01": 7983,
      "2020-06-01": 7079,
      "2020-07-01": 9150,
      "2020-08-01": 8895,
      "2020-09-01": 8374,
      "2020-10-01": 6060,
      "2020-11-01": 920,
      "2020-12-01": 382,
      "2021-01-01": 1
    }
  }
}

To make this response more pythonic, I think it would be most useful to return:

• a dictionary of {int: int} for the 'month/week of year' intervals
• a dictionary of {datetime: int} for all other intervals.

The pagination metadata is not necessary for this endpoint since the response will always be returned in a single page.

• Add histogram endpoint
• Convert responses appropriately for each interval type
• Docstrings + type annotations
• Usage examples
• Sample response data (for unit tests)
• Sample response data (for docs)
• Unit tests

Built-in formats

I would like to add support for additional response formats for GET /observations (from original REST API): https://www.inaturalist.org/pages/api+reference#get-observations . I am mainly interested in the dwc format for Simple Darwin Core, but will add the rest while I'm at it.

GeoJSON

Another relevant response format that the API doesn't currently provide is GeoJSON FeatureCollections. This would store the coordinates as the feature geometry, and the remaining observation info as feature properties. This is useful for displaying observations in Mapbox / Leaflet. I recently worked on a small PoC that did this, so I plan on cleaning that up a bit and including that as well.

Example:

 {
    "type": "FeatureCollection",
    "features": [{        
            "type": "Feature", 
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -73.1806613975,
                    44.0194705879
                ]
            },
            "properties": {
                "common_name": "Fall Armyworm Moth",
                "observation_id": 2334322,
                "positional_accuracy": 3,
                "quality_grade": "research",
                "taxon_id": 132468,
                "taxon_name": "Spodoptera frugiperda",
                "timestamp": "2015-10-30T20:07:00-05:00",
                "uri": "http://www.inaturalist.org/observations/2334322"
            }
        }
   ]
}

Since the observation response returns a lot of info that may not be needed in a map viewer context, the included properties should be customizable, e.g. by providing an optional list of keys to include. It should also have some sensible default that includes the most basic info; tentatively, the 8 fields shown in the example above would be a good starting point.

Another caveat is that this would obviously only include observations with GPS info and Public geoprivacy. The parameters has[]=geo&observation[geoprivacy]=public should do that. Not sure if Obscured coords should be returned or not.

Summary

In order to show off some of the cool data that iNaturalist provides, combined with the power of python, it would be great to add some examples to the README that make use of data visualization tools.

Background Info

If you are coming here from Hacktoberfest or the good-first-issue topic, welcome! Recommended experience includes:

• Familiarity with iNaturalist
• Familiarity with GitHub-flavored Markdown
• Basic to intermediate experience with the python language
• A plus, but not required: familiarity with pandas or other tabular data processing tools

Tasks

I would like to have examples with at few different different data visualization tools, each making use of one or more pyinaturalist API functions. You could pick any of the following:

1. A basic example using pandas + matplotlib and/or seaborn,
2. A fancier example using bokeh or altair
3. A geospatial example using geoviews

Submission

• Ideally, the example should be in the form of a Jupyter Notebook. If you're not familiar with Jupyter, a python code snippet and an image of the output would be fine as well.
• Submit a pull request with your file(s) under the examples folder.
• Also see the Contributing guide for guidelines on submitting pull requests to this project

Reference & Examples

• Matplotlib tutorial
• Another matplotlib tutorial
• Matplotlib example gallery
• Seaborn example gallery
• Bokeh quickstart
• Bokeh example gallery
• GeoViews tutorial
• Pyinaturalist API documentation
• For more ideas, see existing data visualizations in the iNaturalist web UI, for example the taxon page

Visualization Ideas

These are just some suggestions, so feel free to come up with your own!

Matplotlib:
Pick two species with a predator-prey relationship, and create a scatter plot of their populations in different discrete regions (like all states in the US, or territories & provinces in Canada, or provinces in South Africa, etc.)

Bokeh:

• Create a layered plot comparing average number of observations of a species (or higher rank) throughout the year for all years combined, compared with observations in 2020 only
• Given a selection of a few different orders of insects, create a scatter plot colored by group of observations over time for a particular location
• Or create a scatter plot colored by a third variable instead of discrete groups, such as number of community identifications

GeoViews:

• Create a map of observations from a node_api.get_observations() query

Follow-up from #4 and #5.

Summary

I'd like to propose making the error handling consistent across all API functions by doing the following:

• Make all requests call raise_for_status() before returning the response (currently some, but not all, endpoints do this)
• Add additional custom exception classes for some common error types.
  • The main purpose of this will be to provide more useful/immediately obvious error messages in cases where the existing error is ambiguous or unclear.
  • There are plenty of errors returned by the API that are perfectly clear and don't need to be messed with.
• Make all custom exception classes inherit from requests.HTTPError, in order to make error handling simpler in client code (e.g., so try ... except HTTPError will catch all request errors)
• Make all validation errors related to request parameters raise a subclass of ValueError. This would include both 400 errors returned by the API, and issues caught before sending the request.

This is roughly how I've done API error handling in other projects, but before working on this I'd like to look over some other python API clients out there to see if there are other approaches to consider, especially for handling client-side validation errors. For example, using a serialization framework like marshmallow is a thorough way to handle validation, but I've only done that in API implementations (server side), not in API clients. That might be overkill for pyinaturalist.

New custom exceptions (WIP)

There are plenty more that could be added, but for a start, a custom exception class could be useful for each of the following cases:

• get_controlled_terms(): 422 error if a taxon ID doesn't exist
  • Unintuitive; it's more typical for an API to return a 404 for any operation on a non-existent resource
  • Suggestion: TaxonNotFound
• update_observation(): 500 error from trying to update a nonexistent obs
  • Unintuitive; it's more typical for an API to return a 404 for any operation on a non-existent resource
  • Suggestion: ObservationNotFound (class already exists)
• update_observation(): 410 error from trying to update the observation of a different user
  • Unintuitive; a 403 (not authorized) would be more typical.
  • Suggestion: NotAuthorizedError (and maybe make this a subclass of AuthenticationError?)

As an alternative to passing user credentials as arguments to rest_api.get_access_token(), it would be useful to also have the option of providing these via shell environment variables, for example:

export INAT_USERNAME=""
export INAT_PASSWORD=""
export INAT_APP_ID=""
export INAT_APP_SECRET=""

This is a pretty common pattern in other applications (for example, the AWS CLI), since environment variables offer a bit more flexibility. For example, creds can be stored in the system keychain or other secure format and then loaded with something like export INAT_PASSWORD=$(secret-tool lookup ...).

There is also the python keyring package that provides convenient integration with the system keyring, but that could be a separate issue (EDIT: created #69 for this).

If both function arguments and environment variables were to be specified, function arguments would take precedence.

Follow-up from #48.

Let's start with just adding the two basic projects endpoints:

• GET /projects
• GET /projects/id

I'd like to add the three Places endpoints from the Node API.

Main Tasks

• Endpoints
  • /places/{id}
  • /places/autocomplete
  • /places/nearby
• Docs
  • Doctrings + type annotations
  • Usage examples
  • Update release notes
• Tests
  • Sample response data
  • Unit tests

Other minor changes

• Make get_places_by_id() accept multiple IDs and check that all are valid integers
• Update get_taxa_by_id() to be consistent with get_places_by_id()`
• Convert "location" coordinate strings to floats
• Ensure all observation endpoints also return all coordinates as floats to be consistent with places endpoints
  • Note: Only rest_api.get_observations() (with JSON response format) needed to be updated

Python 3.5 reached EOL on 2020-09-13. I think it would be reasonable to keep pyinaturalist compatible with Python 3.5 through v0.11. For v0.12+, we can remove 3.5 from the tox tests and start making use of Python 3.6 features: f-strings, type annotations for variables, etc.

Also see #32.

It would be useful to show in a concise manner which API endpoints pyinaturalist implements, so a new user can more easily get an idea of the features offered. For that purpose, I'd like to add a table listing all iNaturalist API endpoints, indicating which ones have been implemented in pyinaturalist.

Also, now that the list of API functions has grown, as well as the amount of documentation per function, the docs for the node_api and rest_api modules are now quite long. I'd like to add function summary sections at the top of each of these modules. There are a number of Sphinx extensions that could accomplish this.

It would be useful to have full example responses in our docs. I believe we can reuse the response data we already have for unit tests (test/sample_data).

The only problem is that some of these responses are quite large, and would add tons text to the docs that would be cumbersome to scroll through. So, I would only want to do this if the responses can be put inside collapsible sections that are collapsed by default. Neither Sphinx nor the RTD theme has a feature like that out of the box, but it should be doable with some custom CSS and templates (example 1, example 2).

Another caveat is that some of our functions modify the response data somewhat, like type conversions. The current samples contain the unmodified responses, which are needed for testing said conversions & other response modifications. In those cases (probably 25% of the endpoints or less), it would be fine to just include another copy with the modified response.

Finally, for the sake of code cleanliness, it would be nice (but not required) to implement this in the form of a decorator that takes a path to the sample .json file and modifies the function's docstring with the appropriate Sphinx markup.

E.g, instead of this:

def get_foo(**kwargs):
    """
    [the rest of the docstring]

    Example Response:

        .. container:: toggle

            .. container:: header

                **Show/Hide Example Response**

            .. literalinclude:: sample_response.json
                :language: JSON
    """

We could just write this:

@document_response_format("sample_response.json")
def get_foo(**kwargs):
    """
    [the rest of the docstring]
    """

RIP Travis CI 😢
Travis-ci.org is going read-only next month, and travis-ci.com will no longer have free plans for open-source public repos. Moving to GitHub Actions seems to be the popular choice.

Specific features to reproduce:

• Test multiple python versions
• Run additional style checks + build tests (only run for python 3.8, not all python versions)
• Send test coverage results to Coveralls if all tests pass
• Deploy to pypi using an API token stored in GitHub secrets
• Deploy only if all tests for all python versions passed
• Deploy stable builds on git tags only
• Deploy pre-release builds versioned in the format <major>.<minor>.<patch>.dev<build_number>

Python 3.4 reached EOL in March 2019, and it's been adding a bit of extra work to keep compatibility with it. I'd like to drop this in the release after the next one (which would be v0.11).

Things to clean up/restrictions that would no longer apply:

• Remove from tests and classifiers
• Remove typing backport and use the stdlib version
• Remove merge_two_dicts() and use {**dict, **dict} and other PEP 448 syntax
• Use latest pytest (4.7+)
• Use latest tox (3.15+)
• Use json.JSONDecodeError
• Remove other python 3.4-specific exceptions/workarounds
• Remove requirements.txt; known minimum required package versions are all specified in setup.py now, and remaining version pins are not needed

There is a unified /search endpoint from the Node (v1) API that I would find useful. This appears to be the text search endpoint used by the main search bar on inaturalist.org, which combines results from observations, taxa, places, and possibly other records.

• Add search endpoint
• Doctrings + type annotations
• Usage examples
• Sample response data
• Unit tests

New Endpoints

I am currently playing around with the three taxa endpoints from the iNat Node API:

• /taxa
• /taxa/{id}
• /taxa/autocomplete
  I am working on some simple python wrappers for those. I figured I may as well contribute to this project, since someone else may find those useful. I have a WIP branch here.

Contribution Questions

Before submitting a PR, I have a few questions about contribution guidelines:

• How do you prefer to handle branching? Should PRs be merged into a dev branch, or straight to master?
• How do you prefer to handle versioning? Should any PR with non-trivial changes bump the minor version, or would you like to handle that yourself after merging?
• I see that some wrapper functions take a params dict (like node_api.get_observations(), while others take individual keyword args matching the API request parameters (like rest_api.get_observation_fields()). Personally, in python REST API clients in general, I find individual kwargs more useful. Would that be okay with you?
• Alternatively, another compromise between those two types of function signature would be to accept a generic unpacked **params, document the individual request params, and pass those along to requests. For example:

def get_example_endpoint(user_agent=None, **params):
    """"Example endpoint
        :param int taxon_id: Unique record ID
        :param str rank: Rank of taxa to search
        :param bool is_active: Return only active taxa
    """
    make_inaturalist_api_get_call("example", params, user_agent=user_agent)

# Usage
get_example_endpoint(taxon_id=1234)

That is a little less verbose than individual named keyword arguments, but would lack type hints/autocomplete from within an editor. I don't have a strong preference between the two. What are your thoughts?

Functions that perform pagination like get_all_observations() could be improved. They should use requests.Session to take advantage of its connection pooling, and also request the largest possible page size.

Should we raise Exceptions or just le client code handle that? If the latter, it would be great to at least document what to expect from iNat. Quick check; it seems a bit inconsistent:

• Trying to update a nonexistent obs return error 500, with no more details.
• Trying to update the obs of a different user gives error 410 with details "cette observation n'existe plus".

A few improvements that can be made to the testing & deployment process:

• Update Travis CI config to automatically build and deploy packages to PyPi for tagged commits
• Generate test coverage report with pytest-cov
  • Add coveralls integration
  • Add test coverage badge
• Update documentation in 'Infrastructure' section and merge with 'Contributing' section