Documentation

NOAA NCEI — Temperature & Precipitation (US)

For locations within the United States, historical temperature and precipitation data is sourced from the NOAA National Centers for Environmental Information (NCEI) Daily Summaries dataset via their public API.

• API Endpoint: https://www.ncei.noaa.gov/access/services/data/v1
• Dataset: daily-summaries
• Data Types: TMIN (daily minimum temperature), TMAX (daily maximum temperature), PRCP (daily precipitation)
• Units: Standard (°F for temperature, inches for precipitation)
• Coverage: US locations only (determined by reverse geocoding the search coordinates)
• Fallback: If NCEI is unreachable or returns no data, the system automatically falls back to Open-Meteo historical data
• Used By: Degree Day Calculator, GDD Lookup, Label Data

Nominatim / OpenStreetMap — Geocoding

Location lookups (city/state/country) are resolved to latitude and longitude coordinates using the Nominatim geocoding service. The Label Data page also uses Nominatim's reverse geocoding endpoint to resolve coordinates back to a human-readable city, state, and country name for specimen labels.

• Forward Geocoding: https://nominatim.openstreetmap.org/search
• Reverse Geocoding: https://nominatim.openstreetmap.org/reverse
• Data Types: Latitude, longitude, display name, city, state, country
• Caching: Forward geocode results are cached in Cloudflare KV for 24 hours
• Used By: All pages (forward); Label Data (reverse)

Open-Meteo — Historical Data, Forecast, Elevation & Humidity

Open-Meteo is a free open-source weather API that serves multiple roles in EntoTools:

• Historical Archive Endpoint: https://archive-api.open-meteo.com/v1/archive
• Forecast Endpoint: https://api.open-meteo.com/v1/forecast
• Elevation Endpoint: https://api.open-meteo.com/v1/elevation
• Historical Data: Primary temperature/precipitation source for all non-US locations, and automatic fallback for US locations if NCEI fails. Provides grid-point data derived from reanalysis models.
• Forecast Data: 16-day daily TMAX, TMIN, and precipitation from NWP models (ECMWF, GFS, etc.). Used globally, regardless of the primary data provider.
• Elevation: Meters above sea level for the search coordinates.
• Humidity: Hourly relative humidity at 2m (%). If a collection time is provided, the closest hourly value is used; otherwise, the daily average is reported.
• Used By: All calculators (historical data for non-US, fallback for US, forecast globally), Label Data (elevation, humidity)

Sunrise-Sunset.org — Sunset Time

Sunset times for specimen collection dates are fetched from the Sunrise-Sunset API.

• API Endpoint: https://api.sunrise-sunset.org/json
• Data Types: Sunset time (ISO 8601, converted to local 12-hour format)
• Used By: Label Data

Station Data — NOAA GHCN

A curated set of US weather stations (from NOAA's Global Historical Climatology Network) is stored in stations.json as a static asset. This file contains station IDs, names, and coordinates and is used for nearest-station lookups.

Summary

EntoTools uses the modified Growing Degree Day (mGDD) method, also known as the "modified sine" or "simple average" method with an upper threshold cap.

Formula

Parameters

• Base Temperature (default 50°F): The lower developmental threshold. Days where the average temperature is below this contribute 0 GDD.
• Max Temperature Cap (default 86°F): The upper developmental threshold. TMAX values above this are capped at this value before averaging, because insect development typically plateaus or ceases above certain temperatures.
• Accumulation Start Date: The month and day (e.g., Jan 1) when cumulative GDD resets and begins accumulating for the season.

Accumulation Logic

• Cumulative GDD resets to 0 at the start of each calendar year.
• Daily GDD only accumulates on or after the configured accumulation start date.
• Before the accumulation start date, cumulative GDD remains 0.

Occasionally, a weather station may fail to report temperature data for one or more consecutive days. When this happens, the GDD calculation uses linear interpolation to fill the gap:

• Interpolated values are tagged as Calculated in the data tables and charts.
• If no known day exists on either side of the gap (e.g., missing data at the very start or end of the date range), the gap is left unfilled and those days contribute 0 GDD.
• This ensures the cumulative GDD total remains as accurate as possible even with multi-day data gaps.

When a date range extends to or near the present day, the system appends a 16-day weather forecast to project future temperature and GDD accumulation.

Method

• Source: Forecasts are provided by the Open-Meteo Forecast API, which aggregates output from numerical weather prediction models (ECMWF, GFS, and others).
• Data: Daily high/low temperatures (TMAX/TMIN) and precipitation are fetched in US customary units (°F, inches).
• Coverage: Global — the same forecast endpoint is used regardless of whether the primary data provider is NCEI or Open-Meteo.
• Horizon: Up to 16 days from the current date. Forecast days that overlap with already-available actual data are excluded.

Forecast values are tagged as Forecast in tables and displayed with dashed lines on charts.

The Degree Day Calculator is the primary tool for exploring weather data and GDD trends over custom date ranges.

How to Use

1. Select a location using city/state/country or latitude/longitude coordinates (decimal degrees or DMS).
2. Add date ranges — you can compare multiple time periods side-by-side. Each range appears as a separate series on the charts.
3. Configure GDD parameters: base temperature, max temperature cap, and accumulation start date (month and day).
4. Click Search — data is fetched from the nearest NOAA station and displayed.

Available Charts & Data

• Temperature Chart: Daily high/low temperatures with actual data as solid lines and forecast as dashed lines.
• GDD Chart: Cumulative and daily GDD values. Toggle forecast visibility on/off.
• Precipitation Chart: Daily and cumulative precipitation.
• Data Tables: Detailed breakdowns for temperature, GDD, and precipitation in tabular format.

Saving Searches

Search results can be saved to your browser's local storage for quick access later. Saved searches appear in the sidebar and can be loaded or deleted.

The GDD Lookup provides a quick way to get the cumulative GDD value for a specific location and target date.

How to Use

1. Select a location using city/state/country or lat/lon (decimal degrees or DMS).
2. Set the target date — defaults to today.
3. Configure GDD parameters (base temp, max cap, accumulation start).
4. Click Look Up — the system fetches data from the accumulation start date to the target date and computes cumulative GDD.

Results

The result card shows cumulative GDD, daily GDD for the target date, average temperature, station info, and a full day-by-day breakdown table.

The Label Data tool generates printable specimen labels enriched with weather data (temperature, GDD, precipitation, humidity, elevation, and sunset time) for entomological collections.

How to Use

1. Enter a location using city/state/country or lat/lon (decimal degrees or DMS format, e.g. 35° 27' 23" N).
2. Fill in collection details: site name, date (single or range), time, collector, specimen ID, identification, and determiner.
3. Configure GDD parameters: base temperature and accumulation start date.
4. Click Generate — the system fetches weather data and computes GDD, precipitation, humidity, elevation, and sunset for the collection date(s).
5. Add to label sheet — each entry is accumulated into a multi-label print sheet for batch printing.

Label Contents

• Location (city, state, country) with coordinates and elevation
• Date, sunset time, and collection time
• Temperature (high/low/average), cumulative GDD, 30-day precipitation
• Relative humidity at collection time (or daily average)
• Specimen details: ID, identification, determiner, number of specimens

Data Persistence

Label sheet data is stored in your browser's local storage. It persists between sessions but will be lost if you clear your browser cache.

The Collection Database lets you browse, search, and manage all saved specimen collection records.

Features

• Browse & Sort: View all records sorted by date, location, or other fields.
• Search: Filter records by keyword across all fields.
• Export: Download all records as a CSV file for backup or import into other systems.
• Import: Upload a CSV file to restore or add records to the database.

Provider Routing

The system determines which data provider to use based on the country of the search location:

• United States: NOAA NCEI (station-based). If NCEI fails or returns no stations, the system falls back to Open-Meteo grid-point data.
• All other countries: Open-Meteo historical archive (grid-point data).

When a fallback occurs, a warning banner is displayed on the page indicating that alternative data was used.

Station Selection (US / NCEI)

For US locations, the system automatically finds the best nearby NOAA weather station:

1. Bounding Box Filter: Stations within approximately 140 miles (2° latitude) of the search location are pre-filtered.
2. Distance Ranking: Remaining stations are ranked by haversine distance.
3. Station Type Priority: Stations with IDs starting with USW (airports), USC (cooperative), or USR (regional) are preferred, as they are more likely to report temperature data.
4. Data Verification: The top candidates are checked against NCEI for recent data (last 30 days). The closest station with actual data is selected.

The selected station's name, ID, and distance from your search location are displayed in the results.

Grid-Point Data (Non-US / Fallback)

For non-US locations (or when NCEI fails), Open-Meteo provides data for the exact grid point nearest to the search coordinates. No station selection is performed; instead, the latitude and longitude are used directly.

• Data Availability: NOAA NCEI data may have a 1–3 day lag from the current date. The most recent days might not have data yet. This only affects requests for US locations.
• Station Coverage: Rural areas may have fewer nearby stations, resulting in data from stations farther away. Always check the reported distance, as it is listed in the datasets provided. This only applies to US/NCEI locations.
• Open-Meteo Resolution: Open-Meteo provides gridded reanalysis data, not station-based observations. Its spatial resolution is approximately 9–25 km depending on the model. For non-US locations, this is the only available data source.
• Forecast Accuracy: The 16-day forecast is sourced from Open-Meteo's numerical weather prediction models. Accuracy is generally high for the first 7 days and decreases beyond that.
• Coordinate Input: All pages accept coordinates in decimal degrees (e.g., 35.4564) or DMS format (e.g., 35° 27' 23" N). Locations can also be entered as city/state/country for geocoding via Nominatim.
• Local Storage: Saved searches, label sheets, and the collection database are stored in your browser. They do not sync across devices and can be lost if you clear browser data. We recommend either printing your data and charts, saving the CSV files, and exporting the database when leaving the page. You can re-import the Database CSV file when you return.
• NCEI Rate Limits: The NCEI API may occasionally return 503 errors during high-traffic periods. The system automatically retries up to 3 times with exponential backoff. This only affects requests for US locations.