open-meteo / open-meteo-api-kotlin Goto Github PK

A Kotlin library for the Open-Meteo.com APIs.

License: MIT License

Kotlin 100.00%

api-wrapper kotlin kotlin-jvm kotlin-library open-meteo

open-meteo-api-kotlin's Introduction

🌤 Open-Meteo Weather API

Open-Meteo is an open-source weather API and offers free access for non-commercial use. No API key is required. You can use it immediately!

Head over to https://open-meteo.com! Stay up to date with our blog at https://openmeteo.substack.com.

Features

Hourly weather forecast for up to 16 days
Global weather models with 11 km and regional models up to 1.5 km resolution
Weather model updates every hour for Europe and North America
80 years Historical Weather API
Based on the best weather models: NOAA GFS with HRRR, DWD ICON, MeteoFrance Arome&Arpege, ECMWF IFS, JMA, GEM HRDPS, MET Norway
Marine Forecast API, Air Quality API, Geocoding API, Elevation API, Flood API
Lightning fast APIs with response times below 10 ms
Servers located in Europe and North America with GeoDNS for best latency and high-availability
No API key required, CORS supported, no ads, no tracking, not even cookies
Free for non-commercial use with data under Attribution 4.0 International (CC BY 4.0)
Source code available under AGPLv3

How does Open-Meteo work?

Open-Meteo utilizes open-data weather forecasts provided by national weather services. These services offer numerical weather predictions that are free to download. However, working with these models can be challenging, as it requires expertise in binary file formats, grid-systems, projections, and the fundamentals of weather predictions.

Like many other weather APIs, Open-Meteo integrates high-resolution local and global weather models. Over 2 TB of data are downloaded and processed daily from multiple national weather services. The collected data is then stored in local files using a customized file format and compression technique to enhance access to time-series data such as a 14-day temperature forecast.

In contrast to other weather APIs, Open-Meteo provides complete access to its source code, and all data sources are openly listed, crediting the national weather services for their work. With Docker or prebuilt Ubuntu packages, it is possible to launch your own weather API within minutes. By providing the source code, users can conduct detailed verifications of the weather data processing and even make modifications themselves. Contributions are highly encouraged and welcomed.

The API is available for non-commercial use at no cost. Despite being free of charge, the forecast accuracy is top-notch. The API utilizes a vast array of local weather models with rapid updates, ensuring that the most precise forecast is generated for any location globally.

Resources

All API documentation can be found on https://open-meteo.com. The source code for the website, documentation and API generator is available here: https://github.com/open-meteo/open-meteo-website
The free non-commerical API is hosted at https://api.open-meteo.com using to GeoDNS to servers in Europe and North America (HTTPS is optional). The API source code is in this current repository.
The geocoding API source code is available in a separate repository https://github.com/open-meteo/geocoding-api
Larger changes are announced in the Open-Meteo Blog
The Open-Meteo weather database is redistributed as part of an AWS Open-Data Sponsorship

Who is using Open-Meteo?

Apps:

Weather.io A simple Progressive Web App (PWA) for checking the weather.
WeatherGraph Apple Watch App
Slideshow Digital Signage app for Android
weewx-DWD Weather forecasts etc. for WeeWX
omWeather Android Weather App
solXpect Android app which forecasts the output of your solar power plant
Raindrop Simple and intuitive weather app for the linux terminal.
Weatherian Multi-model meteogram (multi-platform)
WeatherAI WeatherAI offers an intuitive user experience that makes checking the weather a breeze.
Weather Free, open source, simple and complete weather app for Android
DroneWeather Weather forecasts, satellite count, and KP index for drone pilots.
Clima Beautiful, minimal, and fast weather app
SkyMuse Minimal, privacy-respecting weather app. Built with web technologies.
Weather Please Clean and minimal new tab replacement for browsers
QuickWeather Fast, free, and open source Android app
Rain Free, open source, beautiful, minimal and fast weather app
WetBulb A simple app that shows you the wetbulb temp 24h forecast and tells you if it is dangerous.
OSS Weather - Multi-model/multi-provider Open Source Android/iOS Weather app
The Weather A detailed, installable, progressive web application
Lively Weather Windows native weather app powered by DirectX12 animations.
PointWx Dash application with interactive plots (from beginner-friendly to weather-enthusiast level) easily deployable
MeteoHist A web app to create interactive temperature and precipitation graphs for places around the world

Repositories:

Captain Cold Simple Open-Meteo -> Discord integration
wthrr-the-weathercrab Weather companion for the terminal
Weather-Cli A CLI program written in golang that allows you to get weather information from the terminal
Homepage A highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.
Spots Guru Weather forecast for lazy, the best wind & wave spots around you.
WeatherReport.jl A simple weather app for the Julia REPL

Other:

Menubar Weather A Raycast extension that displays live weather information in your menu bar
MiniPavi Vintage French Minitel (a kind of BBS) weather forecast service (type "METEO" keyword on welcome Minitel screen)
Contributions welcome!

Do you use Open-Meteo? Please open a pull request and add your repository or app to the list!

Client SDKs

Go https://github.com/HectorMalot/omgo
Python https://github.com/m0rp43us/openmeteopy
Kotlin https://github.com/open-meteo/open-meteo-api-kotlin
.Net / C# https://github.com/AlienDwarf/open-meteo-dotnet
PHP Laravel https://github.com/michaelnabil230/laravel-weather
R https://github.com/tpisel/openmeteo
PHP Symfony 6.2 https://gitlab.com/flibidi67/open-meteo
PHP for Geocoding API: https://gitlab.com/flibidi67/open-meteo-geocoding
Android library for Geocoding API: https://github.com/woheller69/OmGeoDialog
Rust: https://github.com/angelodlfrtr/open-meteo-rs

Contributions welcome! Writing a SDK for Open-Meteo is more than welcome and a great way to help users.

Support

If you encounter bugs while using Open-Meteo APIs, please file a new issue ticket. For general ideas or Q&A please use the Discussion section on Github. Thanks!

For other enquiries please contact [email protected]

Run your own API

Instructions to use Docker to run your own weather API are available in the getting started guide.

Terms & Privacy

Open-Meteo APIs are free for open-source developer and non-commercial use. We do not restrict access, but ask for fair use.

If your application exceeds 10'000 requests per day, please contact us. We reserve the right to block applications and IP addresses that misuse our service.

For commercial use of Open-Meteo APIs, please contact us.

All data is provided as is without any warranty.

We do not collect any personal data. We do not share any personal information. We do not integrate any third party analytics, ads, beacons or plugins.

Data License

API data are offered under Attribution 4.0 International (CC BY 4.0)

You are free to share: copy and redistribute the material in any medium or format and adapt: remix, transform, and build upon the material.

Attribution: You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.

You must include a link next to any location, Open-Meteo data are displayed like:

Weather data by Open-Meteo.com

Source Code License

Open-Meteo is open-source under the GNU Affero General Public License Version 3 (AGPLv3) or any later version. You can find the license here. Exceptions are third party source-code with individual licensing in each file.

open-meteo-api-kotlin's People

Stargazers

Watchers

Forkers

leocolman

open-meteo-api-kotlin's Issues

Publish to MavenCentral

Jitpack is awesome, but Maven Central is more usual for Kotlin users (we use it instead of Jitpack, for instance :P)

The process is easier than it looks. It requires proving domain ownership on a Jira ticket and uploading artifacts to a different repository.

I can help with the account setup and the repository adaptations if needed.
A pet project of mine is published to Maven Central and it's very simple, so it can be used as a guide if one is needed: https://github.com/LeoColman/SimpleCpfValidator

Self host version support

You can make the URL of the API can change to support self host server.

(After 1.0) Add repository to Kotlin-Awesome

https://github.com/KotlinBy/awesome-kotlin

openmeteo-api 1.1.4 | ubuntu version

wrong repo , sorry

decodeLong is not precise

When de-serializing a Unix timestamp (e.g.: in the Historical API), the times are 1 or 2 seconds wrong: HistoricalEndpointTest
Testing the deserializing function itself, one can see that it's not a problem related to the Time class, but rather to decodeLong.

This happens both with String and InputStream as sources.

Kotlin multiplatform and flatbuffer support

Is your feature request related to a problem? Please describe.
The project is currently on halt, since kmp support for flatbuffers is not yet fully working.

Describe the solution you'd like
Either:

stop waiting for kmp support --> work on flatbuffer support, and later on rewrite everything as KMP
a) less work now, more later
b) a bit stupid IMHO, since java library already exists, and it can be imported in kotlin, making this one "redundant"
manually implement kmp flatbuffer classes --> rewrite from scratch everything already
a) more work now, less later
b) I honestly don't have much time during the week, but I could cut out some time on weekends to work on it
c) If I work too slowly and the flatbuffer compiler gets kmp fully implemented then all the work is going to be wasted
work on the actual flatbuffer compiler and then come back to this project
a) it would be a ton of work for me, since I have absolutely no idea of how the flatc compiler works
b) would benefit other devs as well

Additional context

Google flatbuffer repo has a few PRs waiting to be merged
Main issue is silent since September, but was already moving slow before
Java SDK already implemented in the repo

PS: I know this is more like a personal note, but feel free to comment on wtf I should do (or what you could do to help 😄)

Crash with no network connection, or server down

Describe the bug
When I call forecast API data, if server down or no internet, app will crash.

To Reproduce

        val query = Forecast.Query(
            latitude = location!!.latitude.toFloat(),
            longitude = location.longitude.toFloat(),
            daily = Forecast.Daily { listOf(
                weathercode,temperature2mMax, temperature2mMin
            ) },
            hourly = Forecast.Hourly { listOf(
                temperature2m
            ) },
            currentWeather = true,
            timezone = Timezone.auto
        )
        //Forecast(query).getOrThrow().run {
        Forecast.invoke(query, URL(Config.WEATHER_API_URL))

Logs

Fatal Exception: java.net.UnknownHostException: Unable to resolve host "api.server.com": No address associated with hostname
       at java.net.Inet6AddressImpl.lookupHostByName(Inet6AddressImpl.java:156)
       at java.net.Inet6AddressImpl.lookupAllHostAddr(Inet6AddressImpl.java:103)
       at java.net.InetAddress.getAllByName(InetAddress.java:1152)
       at com.android.okhttp.Dns$1.lookup(Dns.java:41)
       at com.android.okhttp.internal.http.RouteSelector.resetNextInetSocketAddress(RouteSelector.java:178)
       at com.android.okhttp.internal.http.RouteSelector.nextProxy(RouteSelector.java:144)
       at com.android.okhttp.internal.http.RouteSelector.next(RouteSelector.java:86)
       at com.android.okhttp.internal.http.StreamAllocation.findConnection(StreamAllocation.java:176)
       at com.android.okhttp.internal.http.StreamAllocation.findHealthyConnection(StreamAllocation.java:128)
       at com.android.okhttp.internal.http.StreamAllocation.newStream(StreamAllocation.java:97)
       at com.android.okhttp.internal.http.HttpEngine.connect(HttpEngine.java:289)
       at com.android.okhttp.internal.http.HttpEngine.sendRequest(HttpEngine.java:232)
       at com.android.okhttp.internal.huc.HttpURLConnectionImpl.execute(HttpURLConnectionImpl.java:465)
       at com.android.okhttp.internal.huc.HttpURLConnectionImpl.getResponse(HttpURLConnectionImpl.java:411)
       at com.android.okhttp.internal.huc.HttpURLConnectionImpl.getResponseCode(HttpURLConnectionImpl.java:542)
       at com.android.okhttp.internal.huc.DelegatingHttpsURLConnection.getResponseCode(DelegatingHttpsURLConnection.java:106)
       at com.android.okhttp.internal.huc.HttpsURLConnectionImpl.getResponseCode(HttpsURLConnectionImpl.java:30)
       at com.openmeteo.api.common.http.Endpoint.response(Endpoint.kt:65)
       at com.openmeteo.api.common.http.Endpoint.get(Endpoint.kt:76)
       at com.openmeteo.api.Forecast.invoke-gIAlu-s(Forecast.kt:361)

Caused by android.system.GaiException: android_getaddrinfo failed: EAI_NODATA (No address associated with hostname)
       at libcore.io.Linux.android_getaddrinfo(Linux.java)
       at libcore.io.ForwardingOs.android_getaddrinfo(ForwardingOs.java:133)
       at libcore.io.BlockGuardOs.android_getaddrinfo(BlockGuardOs.java:222)
       at libcore.io.ForwardingOs.android_getaddrinfo(ForwardingOs.java:133)
       at java.net.Inet6AddressImpl.lookupHostByName(Inet6AddressImpl.java:135)
       at java.net.Inet6AddressImpl.lookupAllHostAddr(Inet6AddressImpl.java:103)
       at java.net.InetAddress.getAllByName(InetAddress.java:1152)
       at com.android.okhttp.Dns$1.lookup(Dns.java:41)
       at com.android.okhttp.internal.http.RouteSelector.resetNextInetSocketAddress(RouteSelector.java:178)
       at com.android.okhttp.internal.http.RouteSelector.nextProxy(RouteSelector.java:144)
       at com.android.okhttp.internal.http.RouteSelector.next(RouteSelector.java:86)
       at com.android.okhttp.internal.http.StreamAllocation.findConnection(StreamAllocation.java:176)
       at com.android.okhttp.internal.http.StreamAllocation.findHealthyConnection(StreamAllocation.java:128)
       at com.android.okhttp.internal.http.StreamAllocation.newStream(StreamAllocation.java:97)
       at com.android.okhttp.internal.http.HttpEngine.connect(HttpEngine.java:289)
       at com.android.okhttp.internal.http.HttpEngine.sendRequest(HttpEngine.java:232)
       at com.android.okhttp.internal.huc.HttpURLConnectionImpl.execute(HttpURLConnectionImpl.java:465)
       at com.android.okhttp.internal.huc.HttpURLConnectionImpl.getResponse(HttpURLConnectionImpl.java:411)
       at com.android.okhttp.internal.huc.HttpURLConnectionImpl.getResponseCode(HttpURLConnectionImpl.java:542)
       at com.android.okhttp.internal.huc.DelegatingHttpsURLConnection.getResponseCode(DelegatingHttpsURLConnection.java:106)
       at com.android.okhttp.internal.huc.HttpsURLConnectionImpl.getResponseCode(HttpsURLConnectionImpl.java:30)
       at com.openmeteo.api.common.http.Endpoint.response(Endpoint.kt:65)
       at com.openmeteo.api.common.http.Endpoint.get(Endpoint.kt:76)
       at com.openmeteo.api.Forecast.invoke-gIAlu-s(Forecast.kt:361)

Automatic options fetching script failing

Describe the bug
The automation .github scripts used to automatically generate the Daily/Hourly/Minutely15 Options objects fail.

To Reproduce
Steps to reproduce the behaviour:

Open a console in the root folder
Try running models="" endpoint=Forecast .github/scripts/options.sh
See error

Expected behaviour
Expected console output of all Options objects, ready to get parse in all endpoints.

Library

Version: 0.7.1-beta.1

Additional context
Didn't update the path after code refactoring to migrate to IntelliJ IDEA with commit 972961e5 + overall failure to parse the HTML data.

Issue with URL encoding

Hi
First of, thank you for the time you invested in this library. Looks very handy to use.

Issue with Version: V0.4.0.alpha.0

I tried to execute the example code for the current weather, that you have in the wiki and i received an error.
When I dig deeper into the code i saw that the query URL was already url-encoded.
If I removed the urlEncode(...) in line 101 of Query.kt the example worked for me again.
However, i did not try this change with every other possible request.

Did I missunderstand something with the URL encoding, or has there something changed in underlying libraries?
Can you reporoduce the issue?

(There was a second issue while parsing the response. There is a new attribute in the is_day of type Int, so I added this as well in ResponseCurrentWeather.kt. But this is not the topic here)