wotann 0.5.0 → 0.5.39

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

@@ -0,0 +1,232 @@
+# EPA Envirofacts API Reference
+
+## Base URL
+```
+https://data.epa.gov/efservice
+```
+
+Note: The legacy URL `https://enviro.epa.gov/enviro/efservice` may redirect. Use the current base URL above.
+
+## Authentication
+**None required.** Fully public, no API key needed.
+
+## Rate Limits
+- No documented per-user rate limit.
+- Large result sets may time out. Use row limits and pagination.
+
+## URL Pattern
+Envirofacts uses a RESTful URL-based query pattern:
+```
+https://data.epa.gov/efservice/{table}/{column}/{operator}/{value}/.../rows/{start}:{end}/{format}
+```
+
+- **{table}**: Database table name (e.g. `TRI_FACILITY`, `AQS_SITES`).
+- **{column}/{operator}/{value}**: Filter conditions, chained in the URL path.
+- **Operators**: `=` (implicit, just use `/{column}/{value}`), `>`, `<`, `!=`, `BEGINNING` (starts with), `CONTAINING`.
+- **rows/{start}:{end}**: Row range for pagination (0-based).
+- **{format}**: `JSON`, `XML`, `CSV`, `EXCEL`. Appended as the last path segment.
+
+**Multiple filters** are chained sequentially in the URL path.
+
+---
+
+## Key Databases and Tables
+
+### 1. Toxics Release Inventory (TRI)
+
+Tracks releases of toxic chemicals from industrial facilities.
+
+**Key Tables:**
+| Table | Description |
+|-------|-------------|
+| `TRI_FACILITY` | Facility information (name, address, coordinates). |
+| `TRI_REPORTING_FORM` | Annual reporting form data. |
+| `TRI_RELEASE_QTY` | Quantities of releases by media (air, water, land). |
+| `TRI_TRANSFER_QTY` | Quantities transferred off-site. |
+| `TRI_CHEM_INFO` | Chemical information. |
+
+**Example -- TRI facilities in North Carolina:**
+```
+https://data.epa.gov/efservice/TRI_FACILITY/STATE_ABBR/NC/rows/0:9/JSON
+```
+
+**Response:**
+```json
+[
+  {
+    "TRI_FACILITY_ID": "27601MPLNT501WE",
+    "FACILITY_NAME": "EXAMPLE MANUFACTURING PLANT",
+    "STREET_ADDRESS": "501 WEST MAIN ST",
+    "CITY_NAME": "RALEIGH",
+    "COUNTY_NAME": "WAKE",
+    "STATE_ABBR": "NC",
+    "ZIP_CODE": "27601",
+    "LATITUDE": 35.7796,
+    "LONGITUDE": -78.6382,
+    "FEDERAL_FACILITY_FLAG": "NO",
+    "INDUSTRY_SECTOR_CODE": "325",
+    "PRIMARY_SIC_CODE": "2819",
+    "PRIMARY_NAICS_CODE": "325180"
+  }
+]
+```
+
+**Example -- TRI releases of a specific chemical in a state (2022):**
+```
+https://data.epa.gov/efservice/TRI_RELEASE_QTY/STATE_ABBR/TX/REPORTING_YEAR/2022/CHEM_NAME/CONTAINING/BENZENE/rows/0:24/JSON
+```
+
+### 2. Air Quality System (AQS)
+
+Air quality monitoring data from the national monitoring network.
+
+**Key Tables:**
+| Table | Description |
+|-------|-------------|
+| `AQS_SITES` | Monitoring site metadata. |
+| `AQS_MONITORS` | Monitor-level info (parameters measured). |
+| `AQS_ANNUAL_SUMMARY` | Annual summary statistics per monitor. |
+| `AQS_DAILY_SUMMARY` | Daily summary observations. |
+
+**Example -- AQS monitoring sites in California:**
+```
+https://data.epa.gov/efservice/AQS_SITES/STATE_CODE/06/rows/0:9/JSON
+```
+
+**Example -- annual ozone summary for a county:**
+```
+https://data.epa.gov/efservice/AQS_ANNUAL_SUMMARY/STATE_CODE/06/COUNTY_CODE/037/PARAMETER_CODE/44201/rows/0:9/JSON
+```
+
+**Common AQS Parameter Codes:**
+| Code  | Pollutant |
+|-------|-----------|
+| `44201` | Ozone |
+| `42401` | SO2 |
+| `42101` | CO |
+| `42602` | NO2 |
+| `81102` | PM10 |
+| `88101` | PM2.5 (FRM) |
+| `88502` | PM2.5 (non-FRM) |
+| `14129` | Lead (Pb) |
+
+### 3. Facility Registry Service (FRS)
+
+Central registry of EPA-regulated facilities.
+
+**Key Tables:**
+| Table | Description |
+|-------|-------------|
+| `FRS_FACILITY_SITE` | Facility location and identifiers. |
+| `FRS_PROGRAM_FACILITY` | Links facilities to EPA programs. |
+| `FRS_NAICS` | NAICS codes for facilities. |
+| `FRS_SIC` | SIC codes for facilities. |
+
+**Example -- EPA-regulated facilities by zip code:**
+```
+https://data.epa.gov/efservice/FRS_FACILITY_SITE/POSTAL_CODE/90210/rows/0:9/JSON
+```
+
+### 4. Safe Drinking Water (SDWIS)
+
+Public drinking water system data.
+
+**Key Tables:**
+| Table | Description |
+|-------|-------------|
+| `WATER_SYSTEM` | Water system info. |
+| `VIOLATION` | Drinking water violations. |
+| `LCR_SAMPLE_RESULT` | Lead and Copper Rule sample results. |
+
+**Example -- drinking water violations in a state:**
+```
+https://data.epa.gov/efservice/VIOLATION/PWSID/BEGINNING/OH/rows/0:19/JSON
+```
+
+### 5. Greenhouse Gas Reporting (GHG)
+
+Facility-level greenhouse gas emissions data.
+
+**Key Tables:**
+| Table | Description |
+|-------|-------------|
+| `PUB_DIM_FACILITY` | GHG reporting facility info. |
+| `PUB_FACTS_SECTOR_GHG_EMISSION` | Emissions by sector. |
+
+**Example -- GHG facilities in a state:**
+```
+https://data.epa.gov/efservice/PUB_DIM_FACILITY/STATE/TX/rows/0:9/JSON
+```
+
+---
+
+## Query Patterns
+
+### Filtering with operators
+```
+# Exact match (implicit =)
+/TABLE/COLUMN/VALUE/JSON
+
+# Greater than
+/TABLE/COLUMN/>/VALUE/JSON
+
+# Less than
+/TABLE/COLUMN/</VALUE/JSON
+
+# Not equal
+/TABLE/COLUMN/!=/VALUE/JSON
+
+# Starts with
+/TABLE/COLUMN/BEGINNING/VALUE/JSON
+
+# Contains
+/TABLE/COLUMN/CONTAINING/VALUE/JSON
+```
+
+### Combining filters
+Chain multiple column/value pairs:
+```
+/TABLE/COLUMN1/VALUE1/COLUMN2/VALUE2/JSON
+```
+
+### Pagination
+Use `rows/{start}:{end}` (0-based, inclusive):
+```
+/TABLE/rows/0:99/JSON       # First 100 rows
+/TABLE/rows/100:199/JSON    # Next 100 rows
+```
+Default without `rows`: returns first 10,000 rows.
+
+### Output format
+Append format as the last path segment:
+```
+/TABLE/.../JSON
+/TABLE/.../XML
+/TABLE/.../CSV
+/TABLE/.../EXCEL
+```
+
+---
+
+## AQS Data API (Separate System)
+
+For more granular air quality data, EPA also provides the AQS Data API at:
+```
+https://aqs.epa.gov/data/api
+```
+
+- **Requires:** Free account at https://aqs.epa.gov/data/api/signup?email=YOUR_EMAIL
+- **Auth:** Pass `email` and `key` as query parameters.
+- Key endpoints: `/dailyData/byState`, `/annualData/byState`, `/sampleData/bySite`, `/monitors/byState`.
+
+**Example:**
+```
+https://aqs.epa.gov/data/api/dailyData/byState?email=YOUR_EMAIL&key=YOUR_KEY&param=44201&bdate=20240101&edate=20240131&state=06
+```
+
+## Notes
+- Table and column names are case-insensitive in the URL.
+- The Envirofacts API returns all columns for a table; you cannot select specific columns.
+- For joining data across tables, you must make separate requests and join client-side using shared keys (e.g. `TRI_FACILITY_ID`, `REGISTRY_ID`).
+- Some tables are very large. Always use `rows/` to limit results and paginate.
+- EPA data updates vary by program: TRI is annual, AQS is daily/annual, SDWIS is quarterly.

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

@@ -0,0 +1,237 @@
+# Eurostat API Reference
+
+## Overview
+Eurostat is the statistical office of the European Union, providing statistics on economy, population, trade, labor, environment, and more for EU/EEA member states and partner countries. The API follows the SDMX (Statistical Data and Metadata Exchange) standard.
+
+## Base URL
+```
+https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1
+```
+
+An older JSON-stat endpoint also exists:
+```
+https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0
+```
+
+## Authentication
+**No API key required.** The API is fully open and free.
+
+## Rate Limits
+- No formal rate limits documented.
+- Eurostat may throttle aggressive scraping. Keep automated requests to 1-2 per second.
+- Large datasets may time out; use filters to reduce response size.
+
+---
+
+## Key Endpoints (SDMX 2.1 API)
+
+### 1. Get Dataset (Observations)
+
+```
+GET /data/{datasetCode}/{filter}
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `datasetCode` | Yes | Eurostat dataset code (e.g., `nama_10_gdp`, `demo_pjan`) |
+| `filter` | No | Dot-separated dimension filter. Use `+` for multiple values in a dimension, `.` to separate dimensions, empty segment for "all". |
+
+**Query parameters:**
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `format` | No | `sdmx+json` (default), `sdmx+csv`, `sdmx+xml`, `TSV` |
+| `startPeriod` | No | Start year/quarter/month: `2015`, `2020-Q1`, `2020-01` |
+| `endPeriod` | No | End year/quarter/month |
+| `detail` | No | `full` (default), `dataonly`, `serieskeysonly`, `nodata` |
+| `lang` | No | `en` (default), `fr`, `de` |
+
+**Example (GDP at market prices for Germany and France, annual, 2018-2023):**
+```
+https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/nama_10_gdp/A.CP_MEUR.B1GQ.DE+FR?startPeriod=2018&endPeriod=2023
+```
+
+**Example (total population by country, annual):**
+```
+https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/demo_pjan/A.NR.T.TOTAL.DE+FR+IT+ES?startPeriod=2015&endPeriod=2023
+```
+
+**Example (unemployment rate, seasonally adjusted, monthly):**
+```
+https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/une_rt_m/M.SA.TOTAL.PC_ACT.T.EA20?startPeriod=2023-01&endPeriod=2024-12
+```
+
+**Example (HICP inflation, all items, monthly):**
+```
+https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/prc_hicp_mmor/M.RCH_A.CP00.DE+FR+IT?startPeriod=2023-01&endPeriod=2024-06&format=sdmx+json
+```
+
+### 2. Get Dataset as CSV
+
+Append `?format=sdmx+csv` to any data request for a flat CSV response that is easier to parse.
+
+**Example:**
+```
+https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/data/nama_10_gdp/A.CP_MEUR.B1GQ.DE+FR?startPeriod=2018&endPeriod=2023&format=sdmx+csv
+```
+
+### 3. Get Dataset Structure (Dimensions and Code Lists)
+
+```
+GET /datastructure/ESTAT/{datasetCode}
+```
+
+**Example:**
+```
+https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/datastructure/ESTAT/nama_10_gdp
+```
+
+Returns dimension names, positions, and code list references.
+
+### 4. Get Code List (Dimension Values)
+
+```
+GET /codelist/ESTAT/{codelistId}
+```
+
+**Example:**
+```
+https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/codelist/ESTAT/GEO
+```
+
+### 5. Search/Browse Datasets (Dataflows)
+
+```
+GET /dataflow/ESTAT/all
+```
+
+Returns all available Eurostat datasets. Add `?detail=allstubs` for a lighter listing.
+
+**Example:**
+```
+https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1/dataflow/ESTAT/all?detail=allstubs
+```
+
+---
+
+## JSON-stat API (Simpler Alternative)
+
+### Base URL
+```
+https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data
+```
+
+### Get Data
+```
+GET /data/{datasetCode}?{dimension_filters}
+```
+
+Dimensions are passed as query parameters using their dimension name.
+
+**Example (GDP for DE and FR):**
+```
+https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/nama_10_gdp?geo=DE&geo=FR&unit=CP_MEUR&na_item=B1GQ&freq=A&time=2020&time=2021&time=2022&lang=en
+```
+
+**Response (JSON-stat format):**
+```json
+{
+  "version": "2.0",
+  "label": "GDP and main components (output, expenditure and income)",
+  "id": ["freq", "unit", "na_item", "geo", "time"],
+  "size": [1, 1, 1, 2, 3],
+  "dimension": {
+    "geo": {
+      "label": "Geopolitical entity",
+      "category": {
+        "index": {"DE": 0, "FR": 1},
+        "label": {"DE": "Germany", "FR": "France"}
+      }
+    },
+    "time": {
+      "label": "Time",
+      "category": {
+        "index": {"2020": 0, "2021": 1, "2022": 2}
+      }
+    }
+  },
+  "value": {3336010.0, 3601750.0, 3876810.0, 2310420.0, 2500870.0, 2639090.0},
+  "status": {}
+}
+```
+
+Values are in a flat array; use dimension sizes to reshape.
+
+---
+
+## Common Dataset Codes
+
+| Code | Description |
+|------|-------------|
+| `nama_10_gdp` | GDP and main components |
+| `nama_10_pc` | GDP per capita |
+| `namq_10_gdp` | GDP quarterly |
+| `demo_pjan` | Population on 1 January |
+| `demo_gind` | Population change (births, deaths, migration) |
+| `une_rt_m` | Unemployment rate (monthly) |
+| `une_rt_a` | Unemployment rate (annual) |
+| `lfsi_emp_a` | Employment rate (annual) |
+| `prc_hicp_manr` | HICP inflation (annual rate of change, monthly) |
+| `prc_hicp_mmor` | HICP inflation (monthly rate of change) |
+| `ext_lt_maineu` | EU trade by partner (main partners) |
+| `ext_st_27_2020sitc` | International trade by SITC |
+| `bop_c6_q` | Balance of payments (quarterly) |
+| `gov_10dd_edpt1` | Government deficit/surplus |
+| `gov_10a_main` | Government revenue, expenditure and main aggregates |
+| `sts_inpr_m` | Industrial production (monthly) |
+| `tour_occ_nim` | Tourism (nights spent at accommodation) |
+| `env_air_gge` | Greenhouse gas emissions |
+| `tec00114` | GDP growth rate (percentage change) |
+| `tec00118` | Government debt as % of GDP |
+
+## Common Country Codes (ISO 2-letter, Eurostat uses uppercase)
+
+`AT` Austria, `BE` Belgium, `BG` Bulgaria, `CY` Cyprus, `CZ` Czechia, `DE` Germany, `DK` Denmark, `EE` Estonia, `EL` Greece, `ES` Spain, `FI` Finland, `FR` France, `HR` Croatia, `HU` Hungary, `IE` Ireland, `IT` Italy, `LT` Lithuania, `LU` Luxembourg, `LV` Latvia, `MT` Malta, `NL` Netherlands, `PL` Poland, `PT` Portugal, `RO` Romania, `SE` Sweden, `SI` Slovenia, `SK` Slovakia
+
+Aggregates: `EU27_2020` (EU-27), `EA20` (Euro area 20), `EA19` (Euro area 19), `EEA30_2007` (EEA)
+
+**Note:** Greece uses `EL` (not `GR`) in Eurostat.
+
+## SDMX JSON Response Format
+
+```json
+{
+  "header": {
+    "id": "...",
+    "prepared": "2024-01-15T10:00:00"
+  },
+  "dataSets": [
+    {
+      "series": {
+        "0:0:0:0": {
+          "observations": {
+            "0": [3336010.0],
+            "1": [3601750.0]
+          }
+        }
+      }
+    }
+  ],
+  "structure": {
+    "dimensions": {
+      "series": [...],
+      "observation": [...]
+    }
+  }
+}
+```
+
+In SDMX+JSON, dimension values are encoded as integer indices. The `structure.dimensions` section maps indices to codes and labels. This is compact but requires index lookup.
+
+## Notes
+- Dimension order in the filter path depends on the dataset structure. Always check `/datastructure/ESTAT/{code}` first.
+- Use `+` to select multiple values in one dimension (e.g., `DE+FR+IT`).
+- Leave a dimension segment empty (consecutive dots `..`) to select all values.
+- CSV format (`?format=sdmx+csv`) is recommended for easier parsing -- it returns flat rows with labeled columns.
+- The JSON-stat API is simpler for quick queries but the SDMX API is more powerful and complete.
+- Dataset codes can be found at https://ec.europa.eu/eurostat/databrowser/ by browsing themes.
+- Large unrestricted queries may time out. Always filter by country and time period.

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

@@ -0,0 +1,64 @@
+# OpenFDA API
+
+## Base URL
+```
+https://api.fda.gov
+```
+
+## Auth
+Optional free API key (40 req/min without, 240 req/min with). Register at https://open.fda.gov/apis/authentication/
+Pass as: `?api_key=YOUR_KEY`
+
+## Key Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/drug/event.json` | Drug adverse events (FAERS) |
+| `/drug/label.json` | Drug product labeling (SPL) |
+| `/drug/ndc.json` | NDC directory |
+| `/drug/drugsfda.json` | Drugs@FDA (approvals) |
+| `/drug/enforcement.json` | Drug recalls |
+| `/device/event.json` | Device adverse events |
+| `/device/510k.json` | 510(k) clearances |
+| `/food/event.json` | Food adverse events |
+| `/food/enforcement.json` | Food enforcement |
+
+## Query Parameters
+
+- `search` — query using OpenFDA syntax
+- `count` — count unique values for a field
+- `limit` — results per request (max 1000)
+- `skip` — pagination offset (max 25000)
+
+### Search Syntax
+- Field search: `field:"value"`
+- AND: `field1:value1+AND+field2:value2`
+- OR: `field1:value1+OR+field2:value2`
+- Date range: `field:[20230101+TO+20231231]`
+- Wildcards: `field:aspir*`
+- OpenFDA harmonized fields use `openfda.` prefix
+
+## Example Calls
+
+```
+# Adverse events for aspirin
+/drug/event.json?search=patient.drug.openfda.brand_name:"aspirin"&limit=5
+
+# Top adverse reactions for a drug
+/drug/event.json?search=patient.drug.openfda.generic_name:"metformin"&count=patient.reaction.reactionmeddrapt.exact
+
+# Drug labels by generic name
+/drug/label.json?search=openfda.generic_name:"ibuprofen"&limit=3
+
+# Drug recalls in date range
+/drug/enforcement.json?search=report_date:[20230101+TO+20231231]&limit=10
+
+# Serious adverse events only
+/drug/event.json?search=patient.drug.openfda.brand_name:"warfarin"+AND+serious:1&limit=10
+```
+
+## Rate Limits
+| Tier | Requests/min | Requests/day |
+|------|-------------|-------------|
+| No API key | 40 | 1,000 |
+| With API key (free) | 240 | 120,000 |