Explicit the use of 3 letter country code in API queries

demeringo commented 2 years ago

Bug description

Not really a bug, but I did not notice the fact that API requires a 3 letter country code (like FRA and not FR) when we want to pass usage data to refine impacts.

To be fair, this is explicitly stated in the doc (and a swagger example) but I managed to still miss it 🤷‍♀️, and this is confusing because the API returns results anyway (it returns 'default' impacts).

https://doc.api.boavizta.org/Reference/usage/#usage-location

You can use the device location instead of giving an electrical impact factor. usage_location attribute describe the usage country. The country is represented as as trigram (usually the first three letter of the country). By default, usage_location is set as EU27+1 (Europe of the 27 + England)

But this is not really visible in OpenAPI / Swagger.

To Reproduce

Expected behavior

Short term:

Repeat the info in various sections of the documentation where we could provide usage data (like cloud route).
Repeat the info in swagger

Long term:

could we fail / return an error if a wrong country code is sent ? I understand we still need to support the case where country code is null or empty (in which case we continue to return the defaults impacts).

Additional context

To make thing even more fun, ISO defines both 2 letters and 3 letters country codes: https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes 🤗

da-ekchajzer commented 2 years ago

+1 on your proposal.

If the country code is wrong the API will replace it with the default location (EU). I think that the warning/error is a project on its own ;).

For now, I suggest implementing :

[x] And a route that lists the available country code linked to the verbose name of the country. This route could be used to set up a drop-down list.
[x] Repeat the info in various sections of the documentation where we could provide usage data (like cloud route) as you suggested
[x] Repeat the info in swagger as you suggested

what do you think ?

da-ekchajzer commented 1 year ago

Everything is implemented in the pre-release https://github.com/Boavizta/boaviztapi/releases/tag/v0.2.0-alpha

Boavizta / boaviztapi