# GetFixn starter kit

Storm data for builders. Runnable examples for the TrueFixR storm data API (https://data.truefixr.com).
Docs: https://getfixn.com/docs.html . Recipes: https://getfixn.com/examples.html

## What is in the kit
- `python/`  gf.py (tiny client: retries, cache, rate limit, 402 handling, standard library only) and scripts 01 to 07
- `node/`    gf.mjs (same client for Node 18+) and scripts 01 to 07
- `curl/`    shell scripts 01 to 07
- `webapp/index.html`  one-file web app. Open it in a browser. Paste your own key if you want paid pulls.

## Run something free right now (no key)
    python3 python/01_first_call.py
    node node/01_first_call.mjs
    bash curl/01_first_call.sh

Free previews are limited to 60 requests per minute per IP. They show counts and the exact price of the paid pull.

## Paid pulls (need a key)
Buy a key at https://getfixn.com (minimum $25, prepaid, pay as you go). Then:

    export GETFIXN_KEY=tfx_live_...

Scripts never spend money by accident:
- Every script shows the free preview and the price first.
- Paid pulls only run with an explicit flag (`--pull` / `--go` / `PULL=1`) and a key.
- Storm pulls are capped with `limit=25` in the examples. Raise it on purpose.
- If a call returns HTTP 402 the script stops and prints the price. Top up and run again.

Never commit your key. Keep it in an environment variable.

## Prices (from the live menu)
- ML Storm Forecast by Address (dataset=risk): $0.05 per address
- Model-Based Weather by Address (dataset=weather): lean response free, $0.0002 per call with details=true
- Model-Based Hourly Forecast by Address (dataset=weather with hours_ahead 0 to 48): $0.0002 per call
- Storm History by Address: Reported and Radar-Detected Events Since 2003 (dataset=history): $0.05 per event line, $10 minimum per report
- Past Storm Leads by Address: Reported and Radar-Detected, Last 365 Days (dataset=storms): $0.05 per address
- County forecast status, batch (POST /v1/portfolio/risk, county-level): $0.05 per location
- Hazard score: $0.50 per property
- Daily county digest, coverage and the menu: free

## Good to know
- Send a User-Agent. Python's default urllib User-Agent was blocked (403) when tested; requests, fetch and curl worked.
- Paid record field names are not documented here: `records()` in gf.py / gf.mjs finds the list in the response. Make one small paid call (low `limit`) and look at the shape before writing a parser.
- Past Storm Leads and Storm History are reported and radar-detected events matched to addresses. It is not an inspection or a damage assessment. Forecasts show what could happen, not what will, and can be wrong.
- GetFixn sells data, not trading advice. Nothing here is investment advice. You are responsible for your own strategies and for following the rules of any exchange or market you use.
- Data by TrueFixR. Not affiliated with NOAA or the National Weather Service. Code is provided as is.