External weather and zipcode APIs

[marcvergees]

Weather API:
It closes #564 and all the subissues: #565, #566, #567, #568.
Zipcode API:
closes #548.

[chetanr25]

1. /weather/forecast

The endpoint works and returns results, which is great. I have a few suggestions around documentation and usability:

Coordinate format needs to be documented

When I first tried this, I copied coordinates from Google Maps in the xx°xx'xx.x"N / yy°yy'yy.y"E format. The API expects float values, so it rejected the input. After removing the symbols and characters, I got another error saying the value should be between -90 and 90, which made me realize the decimal point placement was different from what I assumed. It would help a lot if we mention the expected format (decimal degrees, e.g. 70.7000, -72.5000) and the valid range in both the API contract and the Swagger docs.

Date format should be specified

I know the expected date format after working on other projects, but if someone doesn't, they would have to guess and try different formats. The error message does guide us, but it would be more straightforward to mention the expected format (e.g. YYYY-MM-DD) in the API contract and Swagger docs.

The fields parameter needs examples and explanation

I can see there is a fields parameter and description -> "hourly variables" in API Contracts but it is not clear how to use it. After looking at the response, I tried adding a field like soil_temperature_0cm and could see that It returned only this field. It would be really helpful to:

• Add a short description of what fields does (select which weather variables to include in the response)
• List a few examples like ['temperature_2m', 'relative_humidity_2m', 'rain', ...] so users know what kind of values are accepted in the docs. This can go in the API contract and Swagger description for the parameter.

---

2. /zipcode/postal-code

The endpoint summary is "Get Postal Code" but the input is postal_code and it returns an address. So it is doing the opposite of what the name suggests. Based on our discussion in https://github.com/orgs/fireform-core/discussions/539, the requirement is to get the postal code / zip code / pin code when we input an address (town/city, state, country). Right now the implementation is reversed.

3. /zipcode/location

The description says "Fetch data for the given location" but the input is a city name, not lat-long or a specific location. It returns lat-long, country, state code, etc. along with postal code. The bigger problem is that for most locations the postal code field is missing or empty. For a service like FireForm, firefighters cannot afford to miss a record just because the underlying library does not have the data. I think we need to look into alternative libraries or APIs that can reliably return postal codes for given locations.

---

These are just my suggestions. Let me know if I am wrong about anything or if there is context I am missing.

[chetanr25]

Also, I noticed that print statements are being used in this PR.

print statements are generally not recommended, especially in production environments. This is one of the main reasons we introduced logging support to the codebase in #520.

[marcvergees]

Hi @chetanr25, yes you're completely right. There should be some documentation updated. I've alredy submitted again for revision.

Furthermore, I've partially changed the approach of the zipcode resolver with the use of one of the most famous libraries for geocoding: geopy. It still is open-source and I've been testing it with random locations all over the world and works pretty well, it automatically fins locations all over the world without having to specify the country (which used to be kinda a bottleneck for the last one).

Last thing, I've PRed as well some outdated prints we used to have, now redirected through the logger.

[chetanr25]

I was actually planning to remove --progress in a later fix, as it's difficult to tell whether the image is actually being built or not.

Additionally, I think the Docker build process is quite slow and doesn't seem to be using caching effectively. We may need to address this to improve our development speed.

[chetanr25]

This is technically outside the scope of this PR, but replacing print() with logging is definitely an improvement. We had to do this later anyways, Thanks!

[chetanr25]

Based on this example, I entered -122.4194 as the latitude and 37.7749 as the longitude. But latitude should be in the range -90 to +90, and longitude should be in the range -180 to +180.

Suggested change

	Coordinates must be supplied as **decimal degrees** — not degree/minute/second notation. E.g. -122.4194, 37.7749.
	Coordinates must be supplied as **decimal degrees** not degree/minute/second notation. E.g. 37.7749, -122.4194.

[chetanr25]

LGTM

[chetanr25]

I tested it with a few addresses and was able to get the correct ZIP code most of the time. In some cases, the data wasn't available and the API returned an empty list ([]), but I don't think that's a major issue. In such cases, we can prompt firefighters to enter the ZIP code manually. Overall, it worked well for me in most cases.

There is a merge conflict in a file, other than that, LGTM