US Weather Forecast by Coordinates

Get official US National Weather Service forecast periods as flat JSON rows for logistics and outdoor planning, with update times and traceable source URLs.

The actor requests https://api.weather.gov/points/{latitude},{longitude}, follows properties.forecast, and exports its forecast periods in source order. It sends an identifying User-Agent. No API key, address lookup, maps or imagery are needed.

What it returns

Field	Meaning
status	ok for a usable period; error for a free diagnostic
latitude, longitude	Requested decimal-degree coordinates
periodNumber, name, isDaytime	NWS period identifier, label and day/night flag
startTime, endTime	ISO timestamps with source timezone offsets
temperature, temperatureUnit	NWS numeric temperature and F or C; no conversion
windSpeed, windDirection	NWS speed text such as 2 to 6 mph, and compass direction
precipitationProbability	NWS precipitation probability, 0-100 percent; null means unknown
shortForecast	NWS forecast summary
issuedTime, updateTime	NWS properties.updateTime, the forecast update time
generatedAt	NWS response generation timestamp; distinct from forecast update time
sourceUrl	Official grid forecast URL; failed discovery diagnostics may contain the points URL
errorCode, errorMessage	Diagnostic category and explanation; null on successful rows

Weather fields can be absent on diagnostic rows. The dataset's Forecast periods view includes weather and diagnostic fields; the output link opens the dataset items.

Input example

The Console prefill is:

{"latitude":38.8894,"longitude":-77.0352,"maxItems":6}

Latitude and longitude are required numeric values. maxItems defaults to 6 and accepts integers from 1 through 14. It caps all exported rows, including diagnostic rows. Missing coordinates fail with a clear input message instead of querying an unrelated location.

Optional userAgent identifies your application to NWS. Its default is us-weather-forecast/1.0 (Apify coordinate forecast actor). You may add your own public website/contact to it; use 10-256 printable ASCII characters.

Real output example

One row from the local DC run on 2026-10-06; the full six-row dataset is in sample_output.json:

{
  "status": "ok",
  "latitude": 38.8894,
  "longitude": -77.0352,
  "periodNumber": 1,
  "name": "Overnight",
  "startTime": "2026-10-06T03:00:00-04:00",
  "endTime": "2026-10-06T06:00:00-04:00",
  "isDaytime": false,
  "temperature": 46,
  "temperatureUnit": "F",
  "windSpeed": "5 mph",
  "windDirection": "N",
  "precipitationProbability": 0,
  "shortForecast": "Clear",
  "issuedTime": "2026-10-06T06:22:50+00:00",
  "updateTime": "2026-10-06T06:22:50+00:00",
  "generatedAt": "2026-10-06T07:13:38+00:00",
  "sourceUrl": "https://api.weather.gov/gridpoints/LWX/97,71/forecast",
  "errorCode": null,
  "errorMessage": null
}

Pricing

Proposed price: $0.0003 per successful forecast_period, or $0.30 per 1,000 successful periods, plus any Apify platform usage charges. The six-period prefill has $0.0018 in actor event fees. Invalid input and diagnostic rows do not incur this event. Successful cached periods are charged normally.

The proposal is below the most used returned forecast comparable, epctex/weather-scraper, at $0.0006/result, observed 2026-10-06. PRICING.md records the Store API queries, selection scope, competing event units and a free alternative. Pricing must be configured by the owner before publication.

Limits and source behavior

• US NWS land forecast coverage only. Non-US coordinates, unsupported land points and marine points without properties.forecast produce an uncharged diagnostic. Coverage is determined by NWS, not a bounding box.
• One coordinate per run. Requests are sequential, with at most one outstanding request. The actor exports NWS period forecasts, not hourly forecasts, current observations or alerts.
• Coordinates are rounded to four decimal places for the NWS points lookup. Requested coordinates are retained in output.
• Source fields and period lengths are preserved. Missing precipitation is null, not a fabricated zero. Period-level parsing failures become individual diagnostic rows.
• Transient transport failures and HTTP 429/500/502/503/504 get up to four attempts with exponential backoff and jitter. HTTP 429 waits at least five seconds before retrying. Numeric and HTTP-date Retry-After guidance takes precedence; waits longer than 300 seconds are deferred to a later run.
• Forecast payloads are cached by official URL and NWS updateTime in the default key-value store. Cache-Control, Age, Date and Expires bound freshness, with ceilings of one hour for forecasts and one day for point mappings. Expired entries use ETag/Last-Modified validators when available. Source failures do not return stale forecasts.
• Cached data survives restarts when the same key-value store is retained. Separate cloud runs normally have separate default stores; no cross-account shared cache is provided.
• The spending limit is checked before each successful row, and output stops when the SDK reports it reached. Diagnostic rows do not trigger forecast_period; monetization must not also price generic dataset rows.

Official source and retry/coverage guidance: NWS API documentation. NWS data is public and free; the proposed fee covers the actor's extraction and delivery.

Local run and verification

Use the existing shared virtual environment; no packages were installed into it. From this actor directory:

C:/GritWork/earn/.venv/Scripts/python tools/local_run.py
C:/GritWork/earn/.venv/Scripts/python tools/run_checks.py unit
C:/GritWork/earn/.venv/Scripts/python tools/run_checks.py live
apify validate-schema

tools/local_run.py sets APIFY_LOCAL_STORAGE_DIR=<actor>/storage, writes the prefill to storage/key_value_stores/default/INPUT.json if absent, and runs python -m src without the Apify CLI. Edit INPUT.json to change location. Local dataset rows are saved in storage/datasets/default/; SDK __metadata__.json files are storage bookkeeping, not results. Local dataset writes append to existing rows.

tools/verify_delivery.py all runs isolated input probes and compares the real dataset against an independent official response. It clears only each probe's previous dataset to measure per-run rows, and retains cache records for restart checks. Evidence logs include tests, schema validation, source responses and file digests. The container uses apify/actor-python:3.12.

FAQ

Does it resolve city names or addresses? No. Supply numeric coordinates; the actor does not call a geocoding service.

Can I use it outside the US? No. A non-US point returns a coverage diagnostic, not substituted global weather.

Why is rain probability null? NWS did not supply a usable probability. Zero means a supplied zero-percent value; null means unknown.

What is the issue time? issuedTime is NWS updateTime; generatedAt tells you when the API response was generated.

Is this an emergency alert or aviation briefing service? It exports land forecast periods. Alerts and aviation products are outside its scope; consult the relevant official NWS products for those decisions.

Use with AI agents / MCP

After the owner publishes the actor, connect it through the Apify MCP server. Pass numeric latitude, longitude and maxItems, read the default dataset link, and inspect each row's status before using weather values. Preserve sourceUrl and issuedTime when explaining a planning decision; treat null precipitation as unknown and do not invent a numeric wind speed from a range string. This delivery includes the actor, not a separate MCP server; a cloud MCP invocation has not been tested.