Support searching observations by observation fields

[JWCook]

There's an undocumented field:{field_name} param for observations searches, for example: https://www.inaturalist.org/observations?field:Species%20count=2

This can be applied to the following endpoints:

• /observations
• /observations/histogram
• /observations/identifiers
• /observations/observers
• /observations/popular_field_values
• /observations/species_counts

[willkuhn]

I'd love to be able to search on that undocumented field param, both on the observations and observations/species_counts endpoints. Though undocumented, this appears to work correctly through an API query:

• https://api.inaturalist.org/v1/observations/species_counts?field:Species%20count=2
• https://api.inaturalist.org/v1/observations?field:Species%20count=2

It seems like an easy way to allows for querying this param (and potentially other undocumented params) would be to add a "dummy" param for get_observations(), get_observation_species_counts(), and the like that would pass a pre-formatted string like "field:Species%20count=2" directly to the request URL.

[JWCook]

Sure, I'd be happy to add that. It looks like you can search for both a specific value, or just any observations containing a given field.

Usage could look something like this:

# Find observations that contain these fields
get_observations(observation_fields=['Species count', 'Elevation (m)'])

# Find observations that have these specific field values
get_observations(observation_fields={'Species count': 2})

[JWCook]

If you have time, something that would be helpful is to test the other observation endpoints to see if any others allow searching by observation fields.

[willkuhn]

That's a much more elegant solution that the quick-and-dirty work around I envisioned. Wonderful!

Here's a check of other observation endpoints:

• observations/histogram - affirmative - https://api.inaturalist.org/v1/observations/histogram?date_field=observed&interval=month_of_year&field:Species%20count=2
• observations/identifiers - affirmative - https://api.inaturalist.org/v1/observations/identifiers?field:Species%20count=2
• observations/observers - affirmative - https://api.inaturalist.org/v1/observations/observers?field:Species%20count=2
• observations/popular_field_values - affirmative - https://api.inaturalist.org/v1/observations/popular_field_values?place_id=7&field:Species%20count=2
• observations/species_counts - affirmative
• observations/updates - unsure but probably affirmative (misplaced my API auth key)

[JWCook]

I have some changes for this tentatively working, but they still need docs and tests. I'll get that finished up within the next week or so.

[JWCook]

@willkuhn Changes for this are in the latest pre-release build, if you'd like to give it a try.

[JWCook]

@willkuhn FYI, I just realized this conflicts with the fields parameter in the v2 API (#155), so I renamed this parameter to observation_fields. I updated the examples above.