{"id":18320923,"url":"https://github.com/1407arjun/streamlit-owm-connection","last_synced_at":"2025-04-09T14:29:55.567Z","repository":{"id":184938664,"uuid":"672716734","full_name":"1407arjun/streamlit-owm-connection","owner":"1407arjun","description":"A Streamlit experimental connection for the OpenWeatherMap API. Connections Hackathon 2023.","archived":false,"fork":false,"pushed_at":"2023-08-02T01:08:27.000Z","size":53,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-15T08:31:03.532Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://openweathermap-connection.streamlit.app/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/1407arjun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-31T02:12:57.000Z","updated_at":"2023-08-15T06:38:18.000Z","dependencies_parsed_at":"2023-07-31T03:26:41.256Z","dependency_job_id":"c68825b9-6f49-48de-8d04-5a3a24c71992","html_url":"https://github.com/1407arjun/streamlit-owm-connection","commit_stats":null,"previous_names":["1407arjun/streamlit-owm-connection"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1407arjun%2Fstreamlit-owm-connection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1407arjun%2Fstreamlit-owm-connection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1407arjun%2Fstreamlit-owm-connection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1407arjun%2Fstreamlit-owm-connection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/1407arjun","download_url":"https://codeload.github.com/1407arjun/streamlit-owm-connection/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248054973,"owners_count":21040101,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T18:17:54.564Z","updated_at":"2025-04-09T14:29:55.538Z","avatar_url":"https://github.com/1407arjun.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Streamlit OpenWeatherMapConnection\n\nRetrieve current weather and weather forecast for any location by connecting to the OpenWeatherMap API from your Streamlit app. Powered by `st.experimental_connection()` and [requests](https://pypi.org/project/requests/). Works with Streamlit \u003e= 1.22 and Python \u003e= 3.8.\n\nRead more about Streamlit Connections in the [official docs](https://docs.streamlit.io/library/api-reference/connections).\n\n## Installation\nSee the demo directory for a full example of fetching the current weather in different ways by using the city name, coordinates, city ID and zipcode which are supported by the OpenWeatherMap API.\n```\npip install streamlit\npip install git+https://github.com/1407arjun/streamlit-owm-connection\n```\n\n## Initialization methods\nInitialize the connection by either storing it by the name `appid` in the `secrets.toml` file (recommended) or by directly passing it as an argument to the connection. The AppID passed as an argument takes preference over the one stored in the secrets file. Throws a `ValueError` if no AppID is found.\n``` py\nimport streamlit as st\nfrom st_owm_connection import OpenWeatherMapConnection\n\n# OpenWeatherMap API connection (AppID/API Key loaded from secrets.toml)\nconn = st.experimental_connection('owm', type=OpenWeatherMapConnection)\n\n# OR\n# OpenWeatherMap API connection (AppID/API Key passed as argument)\nconn = st.experimental_connection('owm', type=OpenWeatherMapConnection, appid=\"\u003cyour-api-key\u003e\")\n```\n``` toml\n# .streamlit/secrets.toml\n\n[connections.owm]\nappid = \"\u003cyour-api-key\u003e\"\n```\n\nDuring the initialization of the connection, you can also specify global preferences for units and output language, which would be applied to each request made by the connection, unless overridden in the [main methods](#main-methods) or changed by using the [setter methods](#setter-methods). The preferences that can be set are as follows:\n- `units`: Units of measurement (standard/metric/imperial). Defaults to standard.\n- `lang`: Output language. Defaults to English (en). View the supported languages and their codes [here](https://openweathermap.org/current#multi).\n\n``` py\nimport streamlit as st\nfrom st_owm_connection import OpenWeatherMapConnection\n\nconn = st.experimental_connection('owm', type=OpenWeatherMapConnection, units=\"metric\", lang=\"fr\")\n```\n\n## Main methods\n\n### current()\nReturns the current weather at the given location. Refer to the [OpenWeatherMap API docs](https://openweathermap.org/current) for additional information related to response formats and other endpoint-related taxonomy.\n\n\u003e Requires a free OpenWeatherMap API Key.\n\nIt takes in any one of the following named arguments at a time:\n- `q`: The name of the city or city, state code, country code.\n- `lat` and `lon`: The latitude and longitude of the location as floating point numbers.\n- `id`: The city ID, an integer value. Refer to the OpenWeatherMap API docs for a list of valid city IDs.\n- `zip`: The zipcode, country code of the location.\n\n\u003e If none of the above arguments is provided, then the function returns `None`.\n\nApart from the above arguments, it also takes in the following optional arguments, which override the global preferences provided during the initialization for the current request:\n- `units`: Units of measurement (standard/metric/imperial). Defaults to standard.\n- `lang`: Output language. Defaults to English (en). View the supported languages and their codes [here](https://openweathermap.org/current#multi).\n- `ttl`: Time after which the cached response is invalidated. Refer to the [official docs](https://docs.streamlit.io/library/api-reference/performance/st.cache_data).\n\nSome example function calls:\n``` py\nimport streamlit as st\nfrom st_owm_connection import OpenWeatherMapConnection\n\nconn = st.experimental_connection('owm', type=OpenWeatherMapConnection)\n\n# Get weather by city name\nprint(conn.current(q=\"San Francisco\"))\n\n# Get weather by coordinates (latitude and longitude)\nprint(conn.current(lat=43.39, lon=10.54))\n\n# Get weather by city ID\nprint(conn.current(id=833))\n\n# Get weather by zipcode\nprint(conn.current(zip=\"94105,US\"))\n```\n\n### forecast()\nReturns the 3-hour/daily/hourly/30-day weather forecast for the given location. Refer to the corresponding OpenWeatherMap API docs pf [3-hour](https://openweathermap.org/forecast5), [daily](https://openweathermap.org/forecast16), [hourly](https://openweathermap.org/api/hourly-forecast) and [30-day](https://openweathermap.org/api/forecast30) forecasts for additional information related to response formats and other endpoint-related taxonomy.\n\n\u003e 3-hour forecast requires a free OpenWeatherMap API Key.\n\n\u003e Daily forecast requires at least a Startup plan OpenWeatherMap API Key.\n\n\u003e Hourly and 30-day forecast requires at least a Developer plan OpenWeatherMap API Key.\n\nThe `type` positional argument is mandatory and should be one of the following (defaults to 3-hour forecast):\n- `3hr`: Call 5 day / 3 hour forecast data.\n- `daily`: Call 16 day / daily forecast data.\n- `hourly`: Call hourly forecast data.\n- `climate`: Call weather forecast for 30 days.\n\nSimilar to the `current` function, it takes in any one of the following named arguments at a time:\n- `q`: The name of the city or city, state code, country code.\n- `lat` and `lon`: The latitude and longitude of the location as floating point numbers.\n- `id`: The city ID, an integer value. Refer to the OpenWeatherMap API docs for a list of valid city IDs.\n- `zip`: The zipcode, country code of the location.\n\n\u003e If none of the above arguments is provided, then the function returns `None`.\n\nApart from the above arguments, it also takes in the following optional arguments, which override the global preferences provided during the initialization for the current request:\n- `cnt`: A number of timestamps, which will be returned in the API response.\n- `units`: Units of measurement (standard/metric/imperial). Defaults to standard.\n- `lang`: Output language. Defaults to English (en). View the supported languages and their codes [here](https://openweathermap.org/current#multi).\n- `ttl`: Time after which the cached response is invalidated. Refer to the [official docs](https://docs.streamlit.io/library/api-reference/performance/st.cache_data).\n\nSome example function calls:\n``` py\nimport streamlit as st\nfrom st_owm_connection import OpenWeatherMapConnection\n\nconn = st.experimental_connection('owm', type=OpenWeatherMapConnection)\n\n# Get 3-hour weather forecast by city name\nprint(conn.forecast(\"3hr\", q=\"San Francisco\"))\n\n# Get daily weather forecast by coordinates (latitude and longitude)\nprint(conn.forecast(\"daily\", lat=43.39, lon=10.54))\n\n# Get hourly weather forecast by city ID\nprint(conn.forecast(\"hourly\", id=833))\n\n# Get 30-day weather forecast by zipcode\nprint(conn.forecast(\"climate\", zip=\"94105,US\"))\n```\n\n### reset()\nCloses the current session and connection and creates a new [requests session](https://requests.readthedocs.io/en/latest/user/advanced/#session-objects), having the same AppID thereby resetting the previous connection.\n\n### session\nUse `conn.session` to access the underlying requests session object for the current connection.\n\n### units\nUse `conn.units` to access the currently used units for the current connection.\n\n### lang\nUse `conn.lang` to access the currently used output language for the current connection.\n\n## Setter methods\n\n### set_units(units: Literal[\"standard\", \"metric\", \"imperial\"])\n`conn.set_units()` updates the global units preference to the value passed to the function. Must be one from standard/metric/imperial.\n``` py\nconn.set_units(\"imperial\") # Equivalent to conn.units = \"imperial\"\n```\n\n### set_lang(lang: str)\n`conn.set_lang()` updates the global output language preference to the value passed to the function. View the supported languages and their codes [here](https://openweathermap.org/current#multi).\n``` py\nconn.set_lang(\"fr\") # Equivalent to conn.lang = \"fr\"\n```\n\n## Utility methods\n\n### get_icon_url(id: str) -\u003e str\nTakes the icon ID as obtained in the API response and returns the URL to the icon, provided by OpenWeatherMap. An example usage is as follows:\n``` py\nweather = {\n    \"id\": 500,\n    \"main\": \"Rain\",\n    \"description\": \"light rain\",\n    \"icon\": \"10n\"\n}\n\nprint(conn.get_icon_url(id=\"10n\"))\n# Prints https://openweathermap.org/img/wn/10d.png\n```\nCheck out the entire weather conditions taxonomy [here](https://openweathermap.org/weather-conditions).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1407arjun%2Fstreamlit-owm-connection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F1407arjun%2Fstreamlit-owm-connection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1407arjun%2Fstreamlit-owm-connection/lists"}