Multiple issues with species.name_usage(data='vernacularNames')

[niconoe]

I noticed a few issues when trying to do species.name_usage(key=1, language="FRENCH", data='vernacularNames') (example from the documentation, I just changed the key to get some results).

• Doc issue: there's no mention of the possible values for languages ("FRENCH"? "FR"? "fr"? ,"fra"?, ...). We should ideally list the possible values or link to an existing standard.
• The documentation mentions "english" is the default language, but species.name_usage(key=1, data='vernacularNames') returns data in 17 different languages.
• species.name_usage(key=1, language="FRENCH", data='vernacularNames') also returns vernacular names in the 17 languages (the parameter seems ignored).

[niconoe]

According to GBIF's API documentation, the vernacularName endpoint doesn't support the LANGUAGE parameter.

We can either:

• Drop this example from the documentation, and specify which options of name_usage() accept the LANGUAGE parameter.
• Implement language filtering in the function, on GBIF's response. In theory, we should implement pagination first (in case there are more than 1000 results returned, and the requested language appears on a page > 1).

[sckott]

Thanks. I've opened an issue in the gbif forum https://discourse.gbif.org/t/language-and-the-species-api/2188

[niconoe]

Thanks!

The last column of the table "Working with Name Usages" at https://www.gbif.org/developer/species gives information on which endpoint accepts which parameter. Maybe we should make sure pygbif documentation is in sync (or just point users there, to avoid duplication information)?

[sckott]

Right. It's not that much information though, so I think we can point out what routes language works with. And we should make sure to tell users how to specify language. In that forum thread Matt said:

Enumeration for all ISO 639-1 language codes using 2 lower case letters. The enumeration maps to 3 letter codes and Locales.

so language expects a 2 letter iso code, e..g.,

https://api.gbif.org/v1/species/5231190?language=de