API Reference

Weather Class

The main interface for getting weather data.

class get_weather_data.Weather(database_path=None, verbose=False, _db=None, _lookup=None)[source]

High-level API for fetching weather data.

This class provides a simple interface for: - Setting up the station database - Looking up weather data for ZIP codes - Processing CSV files

Example

weather = Weather() weather.setup() result = weather.get(“10001”, “2024-01-15”)

Parameters:

  • database_path (Path | str | None)

  • verbose (bool)

  • _db (Database | None)

  • _lookup (WeatherLookup | None)

database_path: Path | str | None = None
verbose: bool = False
property db: Database

Get the database instance.

property lookup: WeatherLookup

Get the weather lookup instance.

setup(force=False, ghcn_stations=True, usaf_stations=True, zipcodes=True, closest_index=True)[source]

Set up the database with station and ZIP code data.

This downloads station lists and ZIP code data, then builds an index of closest stations for each ZIP code.

Parameters:

  • force (bool) – If True, rebuild even if database exists.

  • ghcn_stations (bool) – Import GHCN stations.

  • usaf_stations (bool) – Import USAF/WBAN (ISD) stations.

  • zipcodes (bool) – Import ZIP code data.

  • closest_index (bool) – Build closest stations index.

Return type:

None

get(zipcode, target_date, elements=None)[source]

Get weather data for a ZIP code and date.

Parameters:

  • zipcode (str) – 5-digit US ZIP code.

  • target_date (str | date) – Date as string (YYYY-MM-DD) or date object.

  • elements (list[str] | None) – List of weather elements to retrieve.

Return type:

WeatherResult

Returns:

WeatherResult with available weather data.

get_range(zipcode, start_date, end_date, elements=None)[source]

Get weather data for a ZIP code over a date range.

Parameters:

  • zipcode (str) – 5-digit US ZIP code.

  • start_date (str | date) – Start date as string (YYYY-MM-DD) or date object.

  • end_date (str | date) – End date as string (YYYY-MM-DD) or date object.

  • elements (list[str] | None) – List of weather elements to retrieve.

Return type:

list[WeatherResult]

Returns:

List of WeatherResult objects, one per day.

process_csv(input_path, output_path, zipcode_column='zip', date_column=None, year_column='year', month_column='month', day_column='day', parallel=True, max_workers=None)[source]

Process a CSV file and add weather data.

Parameters:

  • input_path (str | Path) – Path to input CSV file.

  • output_path (str | Path) – Path to output CSV file.

  • zipcode_column (str | int) – Column name or index for ZIP code.

  • date_column (str | int | None) – Column name or index for date (YYYY-MM-DD).

  • year_column (str | int | None) – Column for year (if no date_column).

  • month_column (str | int | None) – Column for month (if no date_column).

  • day_column (str | int | None) – Column for day (if no date_column).

  • parallel (bool) – Use parallel processing for faster execution.

  • max_workers (int | None) – Number of worker threads (default: CPU count, max 8).

Return type:

int

Returns:

Number of rows processed.

info()[source]

Get database statistics.

Return type:

dict[str, int]

Returns:

Dict with counts of stations and ZIP codes.

WeatherResult

Data returned from weather queries.

class get_weather_data.weather.lookup.WeatherResult(zipcode, date, station_id=None, station_name=None, station_type=None, station_distance_meters=None, tmax=None, tmin=None, tavg=None, prcp=None, snow=None, snwd=None, awnd=None)[source]

Weather data result for a ZIP code and date.

Parameters:

  • zipcode (str)

  • date (date)

  • station_id (str | None)

  • station_name (str | None)

  • station_type (str | None)

  • station_distance_meters (int | None)

  • tmax (float | None)

  • tmin (float | None)

  • tavg (float | None)

  • prcp (float | None)

  • snow (float | None)

  • snwd (float | None)

  • awnd (float | None)

zipcode: str
date: date
station_id: str | None = None
station_name: str | None = None
station_type: str | None = None
station_distance_meters: int | None = None
tmax: float | None = None
tmin: float | None = None
tavg: float | None = None
prcp: float | None = None
snow: float | None = None
snwd: float | None = None
awnd: float | None = None

Database

Low-level database operations.

class get_weather_data.core.database.Database(path=None)[source]

SQLite database for weather station and ZIP code data.

Uses connection pooling and caches station metadata for efficiency.

Parameters:

path (Path | str | None)

connection()[source]

Context manager for database connection (uses pool).

Return type:

Generator[Connection, None, None]

close()[source]

Close the database connection.

Return type:

None

execute(sql, params=())[source]

Execute SQL and return all results.

Return type:

list[tuple[Any, ...]]

Parameters:

  • sql (str)

  • params (tuple[Any, ...])

execute_many(sql, params_list)[source]

Execute SQL with multiple parameter sets.

Return type:

None

Parameters:

  • sql (str)

  • params_list (list[tuple[Any, ...]])

init_schema()[source]

Initialize database schema.

Return type:

None

preload_caches()[source]

Preload all caches for maximum performance.

Return type:

None

get_station_info(station_id)[source]

Get station name and type from cache.

Parameters:

station_id (str) – Station ID.

Return type:

tuple[str, str] | None

Returns:

Tuple of (name, type) or None if not found.

insert_zipcode(zipcode, city, state, lat, lon, county='')[source]

Insert or update a ZIP code.

Return type:

None

Parameters:

  • zipcode (str)

  • city (str)

  • state (str)

  • lat (float)

  • lon (float)

  • county (str)

insert_station(station)[source]

Insert or update a station.

Return type:

None

Parameters:

station (Station)

insert_stations_bulk(stations)[source]

Bulk insert stations.

Return type:

None

Parameters:

stations (list[Station])

get_stations(station_type=None, state=None)[source]

Get stations from database.

Return type:

list[Station]

Parameters:

  • station_type (str | None)

  • state (str | None)

get_zipcode(zipcode)[source]

Get lat/lon for a ZIP code (uses cache).

Return type:

tuple[float, float] | None

Parameters:

zipcode (str)

get_closest_stations(zipcode)[source]

Get cached closest stations for a ZIP code (uses cache).

Return type:

list[tuple[str, int]]

Parameters:

zipcode (str)

set_closest_stations(zipcode, stations)[source]

Cache closest stations for a ZIP code.

Return type:

None

Parameters:

  • zipcode (str)

  • stations (list[tuple[str, int]])

count_zipcodes()[source]

Count ZIP codes in database.

Return type:

int

count_stations(station_type=None)[source]

Count stations in database.

Return type:

int

Parameters:

station_type (str | None)

exists()[source]

Check if database file exists.

Return type:

bool

Station

Weather station data structure.

class get_weather_data.core.distance.Station(id, name, lat, lon, type, state='', elevation=None)[source]

A weather station with location.

Parameters:

  • id (str)

  • name (str)

  • lat (float)

  • lon (float)

  • type (str)

  • state (str)

  • elevation (float | None)

id: str
name: str
lat: float
lon: float
type: str
state: str = ''
elevation: float | None = None