@LocoDelAssembly the sandbox should be updated with the API changes we made allowing annonymous access, right?
(made a new token)
Checking one thing about the update status of the sandbox...
Aha, I see, it needs to be updated.
So- if you want to practice calls (unfortunately with Lepidoptera names), you could switch to hitting this:
https://sandbox.taxonworks.org/api/v1
Luckily we're plannign on updating all the sandboxes today, so if you can stay tuned we'll let you know when that happens- will likely be in around 4 hours. That update will fix the API access issue we see there.
I have to step away for a while- others should be lurking here too, and can start to help, please keep asking questions!
Thank you for your time and help @mjy !
https://sandcastle.taxonworks.org/api/v1/taxon_names?project_token=tF07vts06-PPek48mFtq4A&name=Gryllus
@mjy https://sandcastle.taxonworks.org/api/v1/taxon_names?name=Gryllus&exact=True&project_token=tF07vts06-PPek48mFtq4A returns stuff like Eumodicogryllus, because of True instead of true in python. maybe that makes sense to allow for on your side?
so the intention is that a reader like me makes a query using one of the simple parameters allowed for by /taxon_names, to obtain a bunch of json data of a not-too-big dataset. I iterate through the pages, to glue the complete dataset together to one piece. Then I apply some nosql-json-querying technique to obtain my subset. Correct?
and as I see, the distribution data, the localised names, images and sounds are, like @mjy mentioned, not (yet) accessible this way. It would be awesome, if they would become so!
And another question: Say I would like to access the orthopterafile. At the moment I can do this because you were so kind to create this kind of mirror on your sandcastle. Somehow this exposes only a project 'orthoptera ...' . However, another one like https://sfg.taxonworks.org/api/v1 exposes lepidoptera data (which I do not even find on the regular species file webpage). What is the relation to taxonworks here? The speciesfile databases are respectively a relational database, somewhere, right? So in order to access them via the taxonworks api, one has to make a (local) clone of the complete thing, or be lucky that someone else provides one? I'd be happy to learn how you intended it.
Hi @stegro. Thanks much for all your testing and feedback, it's super useful for us. We'll consider the True/true. I've added an issue: SpeciesFileGroup/taxonworks#1022. In general if you have suggestions like that feel free to add them there. For reference they could, in theory, also be added to https://github.com/SpeciesFileGroup/taxonworks_api/issues (which in afterthought might have been a better place to do so).
You can use as many parameters as you want (not just one at a time), not sure if that is clear. They are added, for the most part, as logical
and (unless otherwise noted).
Your idea is pretty much right on, though in theory we should be tuning the responses to get you pretty much what you need with as few queries as you want. Secondarily parsing the JSON is of course possible too.
You're exactly right about the (vast) majority of available endpoints, they have not yet been exposed to the "api", though they do exist for internal use. We will be prioritizing your use case (given the area, find the specimens, images, and sounds (etc.) in that area), your interactions here pushes us in that direction, and you can also make requests on the issue trackers to further prompt us.
Your last question has more tangents.
- TaxonWorks is a software package, just like, say "Mesquite", or "PAUP". We don't intend for there to be just one instance out there. TaxonWorks is a web-based researcher workbench, it is not intended to be a set of public interfaces, beyond the API that you are playing with. Users logon to use the native interfaces of TaxonWorks. I can create you sandbox accounts to see this.
- The SFG will be moving all their past projects (not just from SpeciesFiles, but 2 other major projects, 3i, and mx) from their backend into TaxonWorks. That migration is in the process, and the results of that migration are being exposed in the different sandboxes.
- The SFG will offer an instance of TaxonWorks (like I said, anyone in theory can serve one up, we go to big effort to help developers do this) as a service to our past users, and to those who are willing to work with us to make it better.
- All the data from past Species Files (and various other projects, including many new ones) are being movied into this Species File Instance (sfg.taxonworks.org) as they become finalized and OK'ed in the sandboxes. That is the LepIndex data you see, and there will be much more.
- The SFG will recreate (new) species pages like those you are familiar with using a seperate set of software tools, perhaps doing exactly what you are doing, navigating through the API to build up the pieces, then transform them into HTML.
- The existing SpeciesFiles are only a tiny subset of what will be in instances of TaxonWorks, both as supported by the SFG, and as supported by other people running a copy of TW.
I hope that helps to clarify the idea.
the /{id} get example shows both a project_id and a project_token. according to the description of the project_id this sounds not right.
Technically it is correct, though it seems redundant. THe use case: If you authenticate with a
token then you can access data in projects that are not exposed yet to the API, i.e. "your" data. Those data can come from many projects, not just one. So you can scope your search to just one of those projects.
token == user based access, project_token == project based access
that is extract a tree of some species relevant for me. if in the future distribution or further information becomes accessible, even the better.
@mjy have a nice weekend, and thanks again!
hm.. now I am wondering why https://sandcastle.taxonworks.org/api/v1/taxon_names?descendants=false&name=Barbitistes+constrictus&project_token=tF07vts06-PPek48mFtq4A&exact=true yields a result, but https://sandcastle.taxonworks.org/api/v1/taxon_names?project_token=tF07vts06-PPek48mFtq4A&name=Isophya+kraussii&exact=true&descendants=false does not. any idea?
The web representation here http://orthoptera.speciesfile.org/Common/basic/Taxa.aspx?TaxonNameID=1137758 indicates an ID, but
curl -X GET 'https://sandcastle.taxonworks.org/api/v1/taxon_names/1137758?project_token=tF07vts06-PPek48mFtq4A' yields success=false
orthoptera of germany: https://we.tl/t-UlOqQw3es0 there still are several issues in the graph, like nodes which are their own parent, many species I am not able to query yet, nodes with multiple parents, nodes with a single parent but multiply connected, etc.
@stegro Really wonderful. Do really let us know if you think something in the response that doesn't match the parameter descriptions in the api doc. I'd also be curious to know why there are "many species" that you are not able to query. Is this because the name strings are not matching up?
Are you requesting only valid names? Are you requesting only Protonyms (come to think of it that param is new and we might not have documented it)?
@mjy I don't understand yet, why. I have a list of binomial names, but unfortunately I am not an expert and I do not know how to decide if they are valid. Some of them could well be species groups or even obsolete. I guess if it is difficult to find them, this is a sign ;) . However, one example is isophya kraussii, which looks pretty valid to me, but see the urls above: "Isophya" and "Isophya+kraussii+kraussi" are found using /taxon_names?name=Isophya , but not "kraussii" and not "Isophya+kraussii". Maybe you see why?
You can tell if a name is considered valid if it's id matches the cached_valid_taxon_name_id. If it doesn't, it's invalid, for one or more of many reasons.
That means we have no blockers, I think, to moving to Rails 6, asside from fixing deprecations etc.
Thanks for the heads up @mjy! I've started a new branch for it to explore: https://github.com/SpeciesFileGroup/taxonworks/tree/rails6
LocoDelAssembly on rails6
Updated gems to use Rails 6 SO… (compare)
LocoDelAssembly on development
Fix typo (compare)
mjy on buffered
Depiction JSON extensions. Fix… (compare)
mjy on buffered
add sqed_depiction flag (compare)
mjy on nexml
wip (compare)
mjy on buffered
depiction end point (compare)
mjy on buffered
stub buffered branch (compare)