Enhancement: Add documentation to clarify country coverage of IDS + add related informative error handling

[t-emery]

From @jakobmiethe.bsky.social:

Hi Teal, playing around a bit and it seems the package throws an error if the geographies argument includes a country for which there is no data (for that specific series?). "API Error Code 160" I expected it to return NAs for those countries but return data for the others. Always an issue when working on tax havens that are sometimes independent countries, sometimes not... Is this intentional? Best, Jakob

I asked for example code, and he provided it:

plotdata <- ids_get(
geographies = "FRA",
series = c("FI.RES.TOTL.DT.ZS"),
# counterparts = "all",
start_date = 1970,
end_date = 2023
)

I guess if I write: plotdata <- ids_get(
geographies = c("VUT","FRA"),
series = c("FI.RES.TOTL.DT.ZS"),
# counterparts = "all",
start_date = 1970,
end_date = 2023
)
I'd expect to get the data for VUT with NAs for FRA but not a break

[christophscheuch]

It's more like a feature request to me than a bug because he requests geographies that are not part of the IDS data due lack of reporting requirements (e.g. FRA, GER, AUT).

In principle, it is possible to provide NA for all geographies that are not part of IDS but we'd need a list of all country and region ISO 3 codes and throw a message (or warning?) like "the country or region you provided is not supported by IDS, returning NAs only" if the provided ID is not part of list_ids_geographies().

If the provided string is not a valid ISO3 code, on the other hand, then I'd expect an error. For instance, if I just ask for data for "XXX", then there should be an error because the request is nonsense.

Alternative: we just add an informative message to the current error "the geography code that you provided is not part of the IDS geographies"

[t-emery]

Yes, now that I look at it more closely, I realize that these are geographies that are not ones covered by the IDS. I'll cover this in the documentation, but also, eventually, we can perhaps add informative error handling that prints a message if someone requests a geography_id that is not included in the database.

I'll change this to feature request.

[JakobMie]

I also think it is more of a feature request but one that other data download software (like the bloomberg terminal) would do as well. It's standard I think. As it stands, if I start with a country list of 10, 4 of which are in the worldbank data (this was my usecase), it becomes quite a bit of trial and error before I have my 4 series and the documentation is not that easy to find, I have to go into the data center and check manually. Especially since the country list is unusual (it includes Fiji but not France for example), one could save the user some time.

Isn't this just a simple lookup on a country list? For standardizing countries, the countrycode package is great with the problem that not recognized countries (Kosovo eg but also places like the Christmas Islands) will not get recognized. It is also not particularily fast. But it takes pretty much any mis-spelling you can come up with and fixes it. Then a pre-check reducing the number of countries asked for to those available with a warning "no IDS data for XYZ" would do it.

[christophscheuch]

The ids_list_geographies() and ids_list_counterparts() functions already ship data that can be used to quickly perform these checks before queries are sent to the API.

In my workflows, I looked up the geographies first in ids_list_geographies() and then performed queries on the subset. However, I understand that this approach is not representative :)

[t-emery]

As I'm updating the documentation as part of issue #50, and I added clarifying language that should partially address this. But I agree that it will still be helpful to add checks into the function that result in actionable error messages.