How do you get all the conservation status fields for a taxon for a particular place?

[benarmstrong]

In https://forum.inaturalist.org/t/establishment-means-in-two-v1-taxa-endpoints-either-not-complete-or-not-consistent/15099/10 I mention this issue. This is kinda like https://forum.inaturalist.org/t/how-can-you-get-the-full-list-of-establishment-means-for-a-taxon/15435 only focusing in on a single record, and for conservation status instead of establishment means.

I don’t want to use any unofficial / unpublished API calls for this, so what I’ve done so far is I have passed preferred_place_id=# (where # is the place requested by the user) in to /v1/taxa/autocomplete and to /v1/taxa/:id in order to get both establishment_means and conservation_status in the result. But what I’m finding is the autocomplete call returns status_name (e.g. "threatened") but not url, which I need. Conversely, the :id call returns url, but not status_name. I can’t always count on the bot having done both calls, so I am missing status_name from some displays, but have included it in others. This is a less than wonderful user experience because most users haven’t memorized all the status codes. It would be wonderful if I could one-stop-shop for all the conservation_status fields in a single API call, but so far, I’ve been unable to find one. Anyone know of one that would include both these pieces of info?

[jwidness]

Can you just build a list to convert the status codes to status_name? I think they’re all here except for IUCN.

[benarmstrong]

Yes, but the less of that kind of code I have to write, the better.

[pisum]

@benarmstrong

I can’t always count on the bot having done both calls

why not?

[benarmstrong]

There are circumstances where a display (either for a taxon or for an observation) has been previously produced to a channel, and then the user interacts with that display to generate a new display (possibly for a different place this time, so the conservation status could change). In that case, the taxon id is all I have to look up, and therefore I don’t have the status_name from the autocomplete call.

[pisum]

but couldn’t you just always just follow up with a call to the autocomplete endpoint? it’s either that or wait+hope for the other endpoint to be changed, right?

[benarmstrong]

Given a taxon_id alone, how does one use the /v1/taxa/autocomplete endpoint to fetch the corresponding record? The best I can do is search for the taxon by name and iterate through all of the results and hope that the one matching the taxon_id is within the first page. That is very likely going to be the case, but it sounds like an even grubbier hack than the one I already am using.

I mean, I could do this: https://api.inaturalist.org/v1/taxa/autocomplete?q=animalia&taxon_id=1 but then i inexplicably get two results, not one, and am at the mercy of elasticsearch to give me the result I actually wanted within the first page. I just don’t like that kind of “slop”, I guess.

[kueda]

To the original issue, there is no endpoint to get the conservation status fields for a taxon for a particular place. However, https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa_id should return all the conservation statuses for the taxon in question, which you can then filter by place if you wish.

[benarmstrong]

Sure. I got that far, but I’m afraid it doesn’t help solve what’s causing me difficulty. Namely, status_name, which is present from the other endpoint is not present here. Here’s a concrete example:

https://api.inaturalist.org/v1/taxa/836799?preferred_place_id=6853

With the preferred_place_id set like that, I get back:

            "preferred_common_name": "Greenland stitchwort",
            "conservation_status": {
                "taxon_id": 836799,
                "status": "S2",
                "authority": "NatureServe",
                "iucn": 40,
                "url": "http://explorer.natureserve.org/servlet/NatureServe?searchName=Minuartia+groenlandica",
                "description": "",
                "source_id": 8,
                "geoprivacy": "open",
                "place": {
                    "id": 6853,
                    "name": "Nova Scotia",
                    "display_name": "Nova Scotia, CA",
                    "admin_level": 1,
                    "ancestor_place_ids": [
                        97394,
                        6712,
                        6853
                    ]
                }
            },

Note the presence of url (good), and the absence of status_name (the problem I’m seeking a solution for).

I also get back, as you say, all the conservation_statuses and yes, those could be filtered by place, but that’s not my actual problem. Also, I have the same problem with the individual record I want from that list:

            "conservation_statuses": [
...
                {
                    "taxon_id": 836799,
                    "status": "S2",
                    "authority": "NatureServe",
                    "iucn": 40,
                    "url": "http://explorer.natureserve.org/servlet/NatureServe?searchName=Minuartia+groenlandica",
                    "description": "",
                    "source_id": 8,
                    "geoprivacy": "open",
                    "place": {
                        "id": 6853,
                        "name": "Nova Scotia",
                        "display_name": "Nova Scotia, CA",
                        "admin_level": 1,
                        "ancestor_place_ids": [
                            97394,
                            6712,
                            6853
                        ]
                    }
                },
...

Again, url is present, but status_name is absent. In fact, it looks identical to the conservation_status entry that was singled out when I passed it preferred_place_id, so I don’t gain anything by looking in conservation_statuses and filtering these.

[kueda]

Ok, I think I understand what you’re saying. The status_name attribute is the name of IUCN-equivalent status encoded in the iucn attribute, so, as implied above, you could just make a local map of iNat IUCN status codes to status names from https://github.com/inaturalist/inaturalist/blob/main/app/models/taxon.rb#L264-L275. Or I guess we could add it, but frankly, we tend to do that mapping in clients ourselves, e.g. in inaturalistjs.

FWIW, that is really just an attempt to choose a rough match from the actual status to an IUCN status. The mapping is not always perfect.

[benarmstrong]

fair. so if it’s in any endpoint at all, that’s already not your preferred way so i shouldn’t count on it?

[kueda]

@benarmstrong

i shouldn’t count on it?

You can count on attributes in the existing API not disappearing, and if they do, please complain, but I would not count on seeing the status_name attribute persist in future versions of the API. We’re currently working on API v2 and while it’s mostly a wrapper around v1, we’re trying to have more consistent responses schemas.