"term_id_or_unknown" query parameter not working with "term_value_id"

Bug Reports
1

Platform (Android, iOS, Website):
Website, API

Browser, if a website issue (Firefox, Chrome, etc) :
Chrome

URLs (aka web addresses) of any relevant observations or pages:
https://www.inaturalist.org/observations?place_id=122851&taxon_id=319974&term_id_or_unknown=12&term_value_id=13
https://www.inaturalist.org/observations?place_id=122851&taxon_id=319974&term_id=12&term_value_id=13

Description of problem
I can’t find many examples of proper usage, but it seems like the “term_id_or_unknown” query parameter is not working as intended. The examples below use web URLs, but the API appears to behave identically.

What I’m trying to do is a query for “all plant observations which are either flowering or have no plant phenology annotation”. But when I try this, it appears that the “term_id_or_unknown” parameter is treated the same as the “term_id” parameter:

https://www.inaturalist.org/observations?place_id=122851&taxon_id=319974&term_id_or_unknown=12&term_value_id=13 shows 58 observations
https://www.inaturalist.org/observations?place_id=122851&taxon_id=319974&term_id=12&term_value_id=13 shows 58 observations

2

break this up into two queries:

  1. without_term_id=12
  2. term_id=12&term_value_id=13

who knows exactly what’s intended except for the person who wrote the code?

when you use term_id_or_unknown + term_value_id, you will get only observations that have your term_id + term_value_id or observations with some other term_id.

when you use term_id_or_unknown + without_term_value_id, you will get observations with no term_id or any annotated observation without your term_id + term_value_id.

…

there’s some related discussion here: https://forum.inaturalist.org/t/identify-filter-without-annotation-not-working-properly/30148/18

1 Like
3

@pisum - thanks for your input, but it doesn’t address the concern I raised. Though the documentation is sparse, it seems like &term_id_or_unknown=12&term_value_id=13 should return all observations with either no Plant Phenology or with Plant Phenology = Flowering. I may be missing something, but it looks to me like it’s not working as documented, and this is a bug and/or incomplete/incorrect documentation.

I don’t think your suggested alternative would work even for people who wanted to do this in two queries. There appears to be another bug with the without_term_id parameter being ignored - e.g.,

https://www.inaturalist.org/observations?place_id=122851&taxon_id=319974&without_term_id=12 shows 223 observations, as does https://www.inaturalist.org/observations?place_id=122851&taxon_id=319974, and there are definitely some in the first group that have no annotation.

4

you mentioned the API earlier. you can go through that. for example: https://jumear.github.io/stirfry/iNatAPIv1_observations?per_page=200&place_id=122851&taxon_id=319974&without_term_id=12&verifiable=true.

the only explanation i see is:

Must have an annotation using this controlled term ID and associated term value IDs or be missing this annotation

does that mean what you suggest? if i read it literally, it seems to suggest that it would get plant phenology = flowering or not ( plant phenology = flowering ) – which means what exactly?

on the other hand, if i take “term_id_or_unknown” literally, that would suggest an observation where term_id = 12 or where not exists (any term id), which isn’t quite what you suggested either.

like i said before, who knows what is intended except for the developer?

5

For term_id_or_unknown, the docs say:

Must be combined with the term_value_id or the without_term_value_id parameter. Must have an annotation using this controlled term ID and associated term value IDs or be missing this annotation.

Based on both my personal reading of this, and also how it works when you combine term_id_or_unknown with without_term_value_id, I think it’s supposed to be

must

  • have an annotation using this controlled term ID and associated term value ID
    or
  • be missing this annotation

So I interpret that to mean term_id_or_unknown=12&term_value_id=13 should bring back obs that

  • do have term_id=12 AND term_value_id=13 (so Flowers and Fruits=Flowers)
    or
  • are missing term_id=12 entirely (Flowers and Fruits=null)

That doesn’t appear to work, so it seems like a bug to me.

6

Interesting. I agree it’s broken for your case. However, it seems to be working exactly as intended when I try to look at pictures of non-dead cats

https://www.inaturalist.org/observations?taxon_id=118552&term_id_or_unknown=17&without_term_value_id=19

7

Here’s a search query for Mt. San Antonio Wildlife Sanctuary, with 1470 verified observations.
https://www.inaturalist.org/observations?place_id=201657&d2=2026-02-25

Here are the number of observations for the various life stages at Mt. San Antonio Wildlife Sanctuary.

60 Adult, term_id=1, term_value_id=2
0 Teneral, term_id=1, term_value_id=3
0 Pupa, term_id=1, term_value_id=4
1 Nymph, term_id=1, term_value_id=5
11 Larva, term_id=1, term_value_id=6
3 Egg, term_id=1, term_value_id=7
4 Juvenile, term_id=1, term_value_id=8
0 Subimago, term_id=1, term_value_id=16

Here are the counts for term_id_or_unknown and without_term_value_id. The counts are fine. They line up with term_id and term_value_id

1410 Adult, term_id_or_unknown=1, without_term_value_id=2
1470 Teneral, term_id_or_unknown=1, without_term_value_id=3
1470 Pupa, term_id_or_unknown=1, without_term_value_id=4
1469 Nymph, term_id_or_unknown=1, without_term_value_id=5
1459 Larva, term_id_or_unknown=1, without_term_value_id=6
1467 Egg, term_id_or_unknown=1, without_term_value_id=7
1466 Juvenile, term_id_or_unknown=1, without_term_value_id=8
1470 Subimago, term_id_or_unknown=1, without_term_value_id=16

term_id_or_unknown and term_value_id does not work. I’m linking to a basic version of api v2 observations to show the bug comes from the api, and not the website. total_results in the api is the number of observations.

391 Adult, term_id_or_unknown=1, term_value_id=2
383 Teneral, term_id_or_unknown=1, term_value_id=3
383 Pupa, term_id_or_unknown=1, term_value_id=4
383 Nymph, term_id_or_unknown=1, term_value_id=5
394 Larva, term_id_or_unknown=1, term_value_id=6
383 Egg, term_id_or_unknown=1, term_value_id=7
383 Juvenile, term_id_or_unknown=1, term_value_id=8
383 Subimago, term_id_or_unknown=1, term_value_id=16

It is very weird bug that 0 Teneral, 0 Pupa, 1 Nymph, 3 Egg, 4 Juvenile, and 0 Subimago term_id + term_value_id all return 383 for term_id_or_unknown + term_value_id.