API function to find concept based on value

[ManonGros]

It would be great to have an API function/endpoint where I can find which concept a value matches to for a given vocabulary.

For example, I would like to know which concept jeune matches to in the life stage vocabulary. Right now I have to query all the labels for all the concept until I find the right one. Instead, I would like to be able to do something like https://api.gbif.org/v1/vocabularies/lifeStage/match?q=jeune and be returned the concept for which the value matches (the value should be matched to any of the hidden or alternative or translation labels).

[CecSve]

This would be very helpful for users and institutions that may want to use a vocabulary to map their data prior to sharing it with GBIF

[marcos-lg]

We have a basic full-text search: https://api.gbif.org/v1/vocabularies/LifeStage/concepts?q=joven

I think jeune is not present in any label.

[ManonGros]

I am confused by that function, if use https://api.gbif.org/v1/vocabularies/Sex/concepts?q=male, I get several concepts. Is there a way to find the concept that the value male would match to?

[CecSve]

I am confused by that function, if use https://api.gbif.org/v1/vocabularies/Sex/concepts?q=male, I get several concepts. Is there a way to find the concept that the value male would match to?

You get all the concepts of the vocabulary, it seems. Ideally, you should only get the concept that the verbatim value maps to (if the hidden value exists of course)

[marcos-lg]

That is a free-text search that matches any concept that has that value. I think what you want is a lookup endpoint but we don't have it (pipelines does a lookup but it's not an API endpoint). We could add it though.

[ManonGros]

I think having a lookup would be really helpful.

[CecSve]

I think having a lookup would be really helpful.

+1

[marcos-lg]

I deployed a lookup endpoint in UAT.

It returns only the fields that match, for example, this matched the concept name:

https://api.gbif-uat.org/v1/vocabularies/LifeStage/concepts/lookup?q=adult

This matched the spanish label:

https://api.gbif-uat.org/v1/vocabularies/LifeStage/concepts/lookup?q=adulto

this matched a hidden label:

https://api.gbif-uat.org/v1/vocabularies/LifeStage/concepts/lookup?q=A

this matched an alternative label:

https://api.gbif-uat.org/v1/vocabularies/LifeStage/concepts/lookup?q=Newborn

you can also filter by language:

https://api.gbif-uat.org/v1/vocabularies/LifeStage/concepts/lookup?q=adulto&lang=PT-pt https://api.gbif-uat.org/v1/vocabularies/LifeStage/concepts/lookup?q=adulto&lang=ES-es

and if the value is not found in that language but exists in English, the English match is returned:

https://api.gbif-uat.org/v1/vocabularies/LifeStage/concepts/lookup?q=newborn&lang=ES-es

@CecSve @ManonGros are you missing something or is there anything you want to change?

EDIT: I renamed the param to q

[ManonGros]

Thanks @marcos-lg ! This looks great! I have been trying to lookup a few things and found that this one: https://api.gbif-uat.org/v1/vocabularies/GeoTime/concepts/lookup?q=přídol doesn't give me what I expect (which would be https://api.gbif-uat.org/v1/vocabularies/GeoTime/concepts/Pridoli). Is it because of the ří?

(This works for example: https://api.gbif-uat.org/v1/vocabularies/GeoTime/concepts/lookup?q=pridolij)

[marcos-lg]

I replace non-ascii characters with their equivalents but it seems that pridol doesn't exist. This works:

https://api.gbif-uat.org/v1/vocabularies/GeoTime/concepts/lookup?q=přídoli

[ManonGros]

Ha! Yes I probably did some wrong copy/pasting. Thanks for checking Marcos! The lookup looks good, it will be very helpful to have.

[marcos-lg]

Deployed to production.

E.g.: https://api.gbif.org/v1/vocabularies/LifeStage/concepts/lookup?q=adulto

[marcos-lg]

Forgot to mention that this also works for the latestRelease endpoints, e.g.: https://api.gbif.org/v1/vocabularies/LifeStage/concepts/latestRelease/lookup?q=adulto

[CecSve]

Thank you! This super useful.