Create API endpoint to find place contained within another place

It would be useful for code written to access the iNat places via the API endpoints to be able to narrow the options when an encompassing place is known. For example, if you simply search for the keyword q=victoria using the /v1/places/autocomplete endpoint, 145 results are returned, only 10 of which are shown, and the top result of which (whether or not you use order_by=area) is unlikely to be what someone in Canada expected.

For example, q=victoria+british+columbia will fail, but a separate query of q=british+columbia will succeed. So putting both together in a compound query like victoria in british columbia (which my proposed bot code that would use the call would parse as two separate queries, the one after the in filtering the one before the in), then the user would be able to get the correct result without knowing in advance the exact keywords in the name that would otherwise precisely match the place for them.

And yes, without too much head-scratching, in this case a reasonably clueful user could enter search terms victoria bc ca or even just victoria bc and get the desired result as the top match, but depending on the place names involved, it can take considerably more effort to find the exact matching terms vs. filtering on a known enclosing place.

Therefore, I propose that the /v1/places/autocomplete endpoint support an optional place_id parameter that can be a place number or list of place numbers, one of which must be present in ancestor_place_ids for a record to match.

You can provide an “ancestor ID” for the older api when searching places: https://www.inaturalist.org/pages/api+reference#get-places

1 Like

Am I supposed to be writing new code for the old API? A slower API with less consistent response formats sounds like something I should be avoiding.

I took a good look at that endpoint and have found that although it supports ancestor_id=, it does not support q= as the /v1/places/autocomplete endpoint does. That doesn’t make solving my problem any easier. Thanks for pointing out the alternate call, though. Had it also provided q=, it might’ve been something I could use.

you could use the site search endpoint to return more than 10 results. i think the way i would find A within B is to do a site search on A and another on B and then compare the two results and see if A.ancestor matches any of the B.ids. if that returns no results (because A has no ancestors defined), you could then do a slightly more complicated match by seeing if A’s point location falls within B’s bounding box, then perhaps narrow that even further via a places nearby query on A’s point location or A’s bounding box to see if B shows up as a nearby place.

i’m not advocating against your original suggestion, but if there is an argument against it, it might be that not all places are created with parent places. so creating filtering functionality based on ancestors might not be useful for a lot of places. maybe iNaturalist’s nearby places search is a more preferred way to search for places.

1 Like

The text at the start of https://api.inaturalist.org/v1/docs/ says:

They are meant to supplement the existing iNaturalist API, implemented in Ruby on Rails, which has more functionality and supports more write operations, but tends to be slower and have less consistent response formats.

So currently (at least) they are expecting the older API to be used too in cases where the newer API doesn’t have the functionality.

1 Like

I found experimentally, site search can do up to 100, ok … (though incidentally if you go over the max & specify per_page=101, it limits the results to 30 per page!)

Looks like for now my best bet is, given a “containing place” that was already located by some other means, then I can use site search as you suggested, e.g. /v1/search/sources=places&per_page=100&q=text and return records from that page that have the “containing place” id in ancestor_ids. If nothing is found on the current page, then more pages would be fetched with page=# until some reasonable limit is reached or there are no more results. This is kludgy and inefficient, but it’s the “least bad” solution I can think of right now.

Your nearby suggestion is intriguing, but I’d rather support that later as a separate near qualifier, since that’s a different sort of search entirely.

Got it. I’m still seeing “slower and less consistent” which reads like a deprecation warning, and getting a bad vibe from that. Let’s see how far the site search gets me before I revisit the idea again. Thanks for your input.