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.
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.
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.
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.
i was thinking of writing a related feature request, but i wonder if i can just expand upon this one?
basically, i was thinking it would be nice if all the parameters available to the get places endpoint in the deprecated API were made available in a new or modified endpoint in the current v1 (and/or upcoming v2) API.
i haven’t seen much movement on this or the related admin-level filtering request, and it doesn’t look like these requests are necessarily being incorporated into the buildout of v2. so i just wanted to bring this up again, while v2 is being built out, in case it makes sense to revisit it at this time…
so in a nutshell, my proposal would be a new or modified get place endpoint in the v1 and/or v2 APIs which would allow filtering by at least:
ancestor
place type (and/or admin level)
establishment means (in conjunction with associated taxon, of course)
It might be worth pointing out that the admin-level filter only works in a very particular way. For example, it does not allow you to ask for all counties in California, or all states that have “new” in the name. Rather, you have to give it a list of known place_ids and it can filter for the ones of a particular admin level.
this is true, but i guess what i was really trying to convey was that if you want a change to the system, the fastest way to get the change might be to code the change yourself.