Mistakes in the API documentation for d1 and d2 of identifications

Platform (Android, iOS, Website): Website

App version number, if a mobile app issue (shown under Settings or About):

Browser, if a website issue (Firefox, Chrome, etc) : Across several browsers including Chrome and Firefox

URLs (aka web addresses) of any relevant observations or pages: https://api.inaturalist.org/v1/docs/#!/Identifications/get_identifications_identifiers

Screenshots of what you are seeing (instructions for taking a screenshot on computers and mobile devices: https://www.take-a-screenshot.org/):

Description of problem (please provide a set of steps we can use to replicate the issue, and make as many as you need.): The API states that an id was created on or before d2. This is not the case, which can be seen most clearly when d1 and d2 are the same day - a query to the api does not return any ids that were created on that day. It is unclear whether the api is functioning correctly and the documentation is wrong or if the document is correct and the api is misfuctioning. Either way, one of them should be fixed.

Step 1: set d1 and d2 to the same date

Step 2: run the query

Step 1 (alt): set d2

Step 2 (alt): run the query

Step 3 (alt): see that ids created on d2 are not counted

As a side point, it appears that there are several parts of the documentation that either need to be updated or have typos. Though they are not the subject of this bug report, if the documentation needs to be edited anyway, it may be worth looking into it

4 Likes

welcome to the forum ;P

1 Like

Thanks!

i think the deal is that the date range parameters here are actually operating based on datetime rather than date.

compare
https://api.inaturalist.org/v1/identifications?d1=2021-01-30&d2=2021-01-30T23:59

and
https://api.inaturalist.org/v1/identifications?d1=2021-01-30&d2=2021-01-30

i noted something similar on another endpoint, i think: https://forum.inaturalist.org/t/1m-observations-this-month/2582/17.

1 Like

radak good catch!

1 Like

So what does that mean for those of us trying to use it? We are concerned we’ve been under-counting peoples IDs in our ID-a-thon project. So for example if we wanted d1=2021-01-24&d2=2021-01-30, do we have to put in some hours in there somehow?

Also how do time zones factor into this?

you would use:
https://api.inaturalist.org/v1/identifications?d1=2021-01-24&d2=2021-01-30T23:59:59

look at the table below, and note that A.total_results = B.total_results - C.total_results:

id query result
A https://api.inaturalist.org/v1/identifications?d1=2021-01-24&d2=2021-01-30T23:59:59&per_page=0 {"total_results":890827,"page":1,"per_page":0,"results":[]}
B https://api.inaturalist.org/v1/identifications?d1=2021-01-24&d2=2021-01-31&per_page=0 {"total_results":890829,"page":1,"per_page":0,"results":[]}
C https://api.inaturalist.org/v1/identifications?d1=2021-01-31&d2=2021-01-31&per_page=0 {"total_results":2,"page":1,"per_page":0,"results":[]}

these particular date range filters appear to operate based on UTC / GMT. that’s why https://api.inaturalist.org/v1/identifications?d1=2021-01-30&d2=2021-01-30 returns a record where “created_at”:“2021-01-29T18:00:00-06:00”.

Thank you. I admit I did not understand your proof table, but adding T23:59:59 to the end seems like an easy enough fix. Now to go back to our project and see just how badly we’ve been miss-reporting our counts for a whole month now…

Edit: oh I get it, the 2 IDs in C were made exactly at 12:00 am

Am I understanding correctly that if we do not specify T59:59:59, identifications made toward the end of the time frame are missing? Perhaps the whole final day is uncounted?

if you don’t specify time, then using the earlier example, you’d effectively be filtering between 2021-01-24 12:00:00AM GMT and 2021-01-30 12:00:00AM GMT, which would not include identifications made between 2021-01-30 12:00:01AM GMT and 2021-01-30 23:59:59PM GMT.

2 Likes

OK, this is all fine and good, but the API documentation does not say any of this, and it should.

Does the same logic apply to dates used in any other parameters? For example we are cutting off the observation created date at Sept 30 2020; are we actually not including that day? Matters less to people probably but I’m curious.

i would assume that every date range parameter operates based on datetime, except for maybe observed date ranges (since those are user submitted, not system generated, and may be difficult to parse into standard datetimes). but the only way to know for sure is to do some queries or check the code.

observation_created_d1=2020-09-30&observation_created_d2=2020-09-30 has no results
observation_created_d1=2020-09-30&observation_created_d2=2020-09-30T23:59:59 has 162888 results
observed_d1=2020-09-30&observed_d2=2020-09-30 has 121971 results
observed_d1=2020-09-30&observed_d2=2020-09-30T23:59:59 has 121971 results

So that’s a bit odd. I’m just going to put T23:59:59 on everything to be safe, since it seems not to hurt.

Perhaps this is because if you enter an observed date manually, you aren’t required to specify the time.

1 Like