libnws

A Python library for retrieving weather data from the US National Weather Service API.

Warning

libnws is under active development and currently doesn't work. This notice will be removed when it's releasable.

Timeline

• July 2024 - Project started
• September 2024 - Stopped work
• February 2025
  • Resumed work
  • Renamed from nwsc to libnws
  • Restricted scope to library only

Contents

• libnws
  • Contents
  • Features
  • Example Usage
  • Dependencies
  • Installation
  • Documentation
  • Purpose
  • Acknowledgements
  • License
  • Contributing

Features

• Retrieves data from all available NWS API endpoints (see endpoint coverage for details)
• Returns measurements in both metric and imperial
• Supported output formats:
  • CSV
  • JSON
  • Plain-text
  • Rich-text
• Supported output destinations:
  • SQLite
  • PostgreSQL
  • File (CSV, JSON, or plain text)
  • STDOUT

Example Usage

To get the weather and the extended forecast in JSON for an address:

import libnws

address = '33 Thomas Street., New York, NY 10007'
weather = libnws.get_weather(address=address, format='json')
forecast = libnws.get_forecast(address=address, forecast='extended', format='json')

print(weather)
print(forecast)

(output here)

To load the hourly forecast for station "KBOS" into a SQLite database:

import libnws

libnws.get_forecast(
    station='KBOS',
    forecast='hourly',
    save_to='sqlite',
    sqlite_path='/path/to/your/sqlite.db' # Omit this to save to ~/.cache/libnws/libnws.db
)

See the examples directory for more.

Dependencies

• requests-cache is the only required dependency
• rich is an optional dependency

Installation

To install without rich:

pip install libnws

To install with rich:

pip install 'libnws[rich]'

Documentation

Note

These markdown files will eventually migrate into the Sphinx docs

• docs/library_api.md
• docs/endpoint_coverage.md
• docs/system_design.md
• docs/configuration.md

Acknowledgements

• Architecture diagram was created with Lucidchart
• Entity-relationship diagrams were created with SQLFlow
• Bruno and Swagger UI were very helpful for exploring the API
• The NWS IT/API team have been responsive on their GitHub page and helpful with troubleshooting endpoint issues
• Parts of the CSV and JSON repositories come from Red Bird's repository pattern examples
• Street address geocoding is done using the US Census Bureau's geocoding service

License

The National Weather Service Library (libnws) is made available under the MIT License

Contributing

See CONTRIBUTING.md for instructions on how to contribute to libnws