wotann 0.5.0 → 0.5.39

package/skills/scientific/database-lookup/references/noaa.md

@@ -0,0 +1,199 @@
+# NOAA Climate Data Online (CDO) API Reference
+
+## Base URL
+```
+https://www.ncdc.noaa.gov/cdo-web/api/v2
+```
+
+## Authentication
+- **API Token: REQUIRED.** Request a free token at https://www.ncdc.noaa.gov/cdo-web/token
+- Pass as HTTP header: `Token: YOUR_TOKEN`
+
+## Rate Limits
+- **5 requests per second** per token.
+- **10,000 requests per day** per token.
+- Queries are limited to **1,000 results per request** (use `offset` for pagination).
+- Date ranges limited to **1 year per request** for the `/data` endpoint.
+
+## Common Parameters (apply to most endpoints)
+| Parameter      | Type   | Required | Default | Description |
+|---------------|--------|----------|---------|-------------|
+| `datasetid`   | string | Varies   | -       | Dataset ID (e.g. `GHCND`, `GSOM`). |
+| `datatypeid`  | string | No       | -       | Data type filter (e.g. `TMAX`, `PRCP`). |
+| `locationid`  | string | No       | -       | Location ID (e.g. `FIPS:37`, `ZIP:28801`, `CITY:US390029`). |
+| `stationid`   | string | No       | -       | Station ID (e.g. `GHCND:USW00013874`). |
+| `startdate`   | string | Varies   | -       | ISO date `YYYY-MM-DD`. |
+| `enddate`     | string | Varies   | -       | ISO date `YYYY-MM-DD`. |
+| `units`       | string | No       | `standard` | `standard` or `metric`. |
+| `limit`       | int    | No       | 25      | Results per page (max 1000). |
+| `offset`      | int    | No       | 1       | Pagination offset (1-based). |
+| `sortfield`   | string | No       | -       | Field to sort by (e.g. `date`, `name`). |
+| `sortorder`   | string | No       | `asc`   | `asc` or `desc`. |
+
+---
+
+## Key Endpoints
+
+### 1. Data (Observations)
+```
+GET /data
+```
+Returns actual observation data. This is the primary data retrieval endpoint.
+
+**Required parameters:** `datasetid`, `startdate`, `enddate`.
+
+**Example -- daily max temperature for a station:**
+```bash
+curl -H "Token: YOUR_TOKEN" \
+  "https://www.ncdc.noaa.gov/cdo-web/api/v2/data?datasetid=GHCND&datatypeid=TMAX&stationid=GHCND:USW00013874&startdate=2024-01-01&enddate=2024-01-31&units=metric&limit=31"
+```
+
+**Response:**
+```json
+{
+  "metadata": {
+    "resultset": {
+      "offset": 1,
+      "count": 31,
+      "limit": 31
+    }
+  },
+  "results": [
+    {
+      "date": "2024-01-01T00:00:00",
+      "datatype": "TMAX",
+      "station": "GHCND:USW00013874",
+      "attributes": ",,W,2400",
+      "value": 12.2
+    },
+    {
+      "date": "2024-01-02T00:00:00",
+      "datatype": "TMAX",
+      "station": "GHCND:USW00013874",
+      "attributes": ",,W,2400",
+      "value": 8.9
+    }
+  ]
+}
+```
+Note: When `units=standard`, GHCND temperature values are in tenths of degrees C. With `units=metric`, they are converted to degrees C.
+
+### 2. Datasets
+```
+GET /datasets
+GET /datasets/{id}
+```
+Lists available datasets or gets details for one.
+
+**Example:**
+```bash
+curl -H "Token: YOUR_TOKEN" \
+  "https://www.ncdc.noaa.gov/cdo-web/api/v2/datasets?limit=10"
+```
+
+**Key Dataset IDs:**
+| ID       | Name | Description |
+|----------|------|-------------|
+| `GHCND`  | Daily Summaries | Global daily station observations (TMAX, TMIN, PRCP, SNOW, etc.) |
+| `GSOM`   | Global Summary of the Month | Monthly aggregates |
+| `GSOY`   | Global Summary of the Year | Annual aggregates |
+| `NORMAL_DLY` | Climate Normals Daily | 30-year daily normals |
+| `NORMAL_MLY` | Climate Normals Monthly | 30-year monthly normals |
+| `PRECIP_15`  | Precipitation 15-Minute | Sub-hourly precipitation |
+| `PRECIP_HLY` | Precipitation Hourly | Hourly precipitation |
+
+### 3. Data Types
+```
+GET /datatypes
+GET /datatypes/{id}
+```
+Lists available data types, optionally filtered by dataset.
+
+**Example:**
+```bash
+curl -H "Token: YOUR_TOKEN" \
+  "https://www.ncdc.noaa.gov/cdo-web/api/v2/datatypes?datasetid=GHCND&limit=50"
+```
+
+**Common GHCND Data Types:**
+| ID     | Description |
+|--------|-------------|
+| `TMAX` | Maximum temperature |
+| `TMIN` | Minimum temperature |
+| `TAVG` | Average temperature |
+| `PRCP` | Precipitation |
+| `SNOW` | Snowfall |
+| `SNWD` | Snow depth |
+| `AWND` | Average wind speed |
+| `WSF2` | Fastest 2-minute wind speed |
+
+### 4. Stations
+```
+GET /stations
+GET /stations/{id}
+```
+Find weather stations, optionally filtered by location, dataset, or extent.
+
+**Additional Parameters:**
+| Parameter  | Type   | Description |
+|-----------|--------|-------------|
+| `extent`  | string | Bounding box: `south_lat,west_lon,north_lat,east_lon`. |
+
+**Example -- stations near Asheville, NC with daily data:**
+```bash
+curl -H "Token: YOUR_TOKEN" \
+  "https://www.ncdc.noaa.gov/cdo-web/api/v2/stations?datasetid=GHCND&locationid=ZIP:28801&limit=10"
+```
+
+**Response:**
+```json
+{
+  "metadata": {"resultset": {"offset": 1, "count": 5, "limit": 10}},
+  "results": [
+    {
+      "elevation": 661.1,
+      "mindate": "1893-01-01",
+      "maxdate": "2024-11-15",
+      "latitude": 35.5951,
+      "name": "ASHEVILLE REGIONAL AIRPORT, NC US",
+      "datacoverage": 1,
+      "id": "GHCND:USW00013874",
+      "elevationUnit": "METERS",
+      "longitude": -82.5572
+    }
+  ]
+}
+```
+
+### 5. Locations & Location Categories
+```
+GET /locations
+GET /locations/{id}
+GET /locationcategories
+GET /locationcategories/{id}
+```
+Browse location hierarchies (countries, states, cities, zip codes, climate regions).
+
+**Example:**
+```bash
+curl -H "Token: YOUR_TOKEN" \
+  "https://www.ncdc.noaa.gov/cdo-web/api/v2/locations?locationcategoryid=ST&limit=52"
+```
+
+Location category IDs: `CITY`, `CLIM_DIV`, `CLIM_REG`, `CNTRY`, `CNTY`, `HYD_ACC`, `HYD_CAT`, `HYD_REG`, `HYD_SUB`, `ST`, `ZIP`.
+
+---
+
+## Workflow: Finding and Querying Data
+
+1. **Find a dataset:** `GET /datasets` to list available datasets.
+2. **Find a station:** `GET /stations?datasetid=GHCND&locationid=ZIP:28801` to find nearby stations.
+3. **Check available data types:** `GET /datatypes?datasetid=GHCND&stationid=GHCND:USW00013874`.
+4. **Query data:** `GET /data?datasetid=GHCND&stationid=GHCND:USW00013874&datatypeid=TMAX,TMIN&startdate=2024-01-01&enddate=2024-12-31&units=metric&limit=1000`.
+
+## Notes
+- The `/data` endpoint enforces a **1-year max date range** per request. For multi-year queries, make sequential requests.
+- Pagination: `offset` is 1-based. Loop until `offset + limit > count` from the metadata.
+- Station IDs include a dataset prefix (e.g. `GHCND:USW00013874`).
+- The `attributes` field in data results contains quality flags (comma-separated). Consult dataset documentation for flag meanings.
+- Token goes in the header, not as a query parameter.

package/skills/scientific/database-lookup/references/omim.md

@@ -0,0 +1,114 @@
+# OMIM (Online Mendelian Inheritance in Man) API Reference
+
+## Base URL
+```
+https://api.omim.org/api
+```
+
+## Authentication
+**API key REQUIRED.** Request at https://omim.org/api (free for academic/non-commercial use).
+- Pass as query parameter: `?apiKey=YOUR_API_KEY`
+- All requests require the key; unauthenticated requests are rejected.
+
+## Rate Limits
+Not publicly documented in detail. Reasonable usage expected per terms of service.
+
+## Response Format
+JSON (with `&format=json`) or XML (default). Always append `&format=json` for JSON responses.
+
+## Key Endpoints
+
+### 1. Entry Lookup (by MIM number)
+```
+GET https://api.omim.org/api/entry?mimNumber={mim_number}&apiKey={key}&format=json
+```
+Example:
+```
+GET https://api.omim.org/api/entry?mimNumber=141900&apiKey=YOUR_KEY&format=json
+```
+Returns entry with title, text, gene map, allelic variants, references.
+
+### 2. Entry with Specific Includes
+```
+GET https://api.omim.org/api/entry?mimNumber=141900&include=text&include=allelicVariantList&include=geneMap&apiKey={key}&format=json
+```
+Include options: `text`, `clinicalSynopsis`, `geneMap`, `allelicVariantList`, `referenceList`, `existFlags`, `externalLinks`.
+
+### 3. Search Entries
+```
+GET https://api.omim.org/api/entry/search?search={query}&apiKey={key}&format=json
+```
+Example — search for "Marfan syndrome":
+```
+GET https://api.omim.org/api/entry/search?search=marfan+syndrome&apiKey=YOUR_KEY&format=json&start=0&limit=10
+```
+
+### 4. Search with Filters
+```
+GET https://api.omim.org/api/entry/search?search={query}&filter=gene&apiKey={key}&format=json
+```
+Filter options: `gene`, `phenotype`, `clinical_synopsis`, etc.
+
+### 5. Gene Map Lookup
+```
+GET https://api.omim.org/api/geneMap?chromosome={chrom}&apiKey={key}&format=json
+```
+Example:
+```
+GET https://api.omim.org/api/geneMap?chromosome=17&apiKey=YOUR_KEY&format=json&start=0&limit=10
+```
+
+### 6. Gene Map Search
+```
+GET https://api.omim.org/api/geneMap/search?search={query}&apiKey={key}&format=json
+```
+
+### 7. Clinical Synopsis Search
+```
+GET https://api.omim.org/api/clinicalSynopsis/search?search={query}&apiKey={key}&format=json
+```
+
+## Response Structure
+```json
+{
+  "omim": {
+    "version": "1.0",
+    "entryList": [
+      {
+        "entry": {
+          "mimNumber": 141900,
+          "status": "live",
+          "titles": {
+            "preferredTitle": "HEMOGLOBIN S; HBS",
+            "alternativeTitles": "SICKLE CELL ANEMIA"
+          },
+          "textSectionList": [...],
+          "geneMap": {
+            "chromosome": "11",
+            "cytoLocation": "11p15.4",
+            "geneSymbols": "HBB"
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+## Pagination
+Use `start` and `limit` query parameters:
+```
+&start=0&limit=20
+```
+
+## MIM Number Types
+- **Asterisk (*)**: Gene
+- **Plus (+)**: Gene with known phenotype
+- **Number sign (#)**: Phenotype (molecular basis known)
+- **Percent (%)**: Phenotype (molecular basis unknown)
+- **Null**: Other entry types
+
+## Notes
+- OMIM data is copyrighted; API access is free for academic use but requires registration.
+- The API does not support bulk downloads; use OMIM downloads page with separate agreement.
+- Cross-reference MIM numbers with ClinVar, NCBI Gene, and HPO for integrated disease analysis.