wotann 0.5.0 → 0.5.39

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

@@ -0,0 +1,283 @@
+# WHO Global Health Observatory (GHO) API Reference
+
+## Overview
+The WHO Global Health Observatory (GHO) OData API provides access to health statistics for 194 WHO member states. It covers over 2000 indicators including life expectancy, disease burden, mortality, immunization coverage, health workforce, air pollution, water/sanitation, and the Sustainable Development Goal (SDG) health indicators.
+
+## Base URL
+```
+https://ghoapi.azureedge.net/api
+```
+
+## Authentication
+**No API key required.** The API is fully open and free.
+
+## Rate Limits
+- No formal rate limits documented.
+- The API is served via Azure CDN and handles moderate loads well.
+- Be respectful with automated requests; 1-2 per second recommended.
+
+---
+
+## Key Endpoints
+
+The API follows the OData v4 protocol. Standard OData query parameters work: `$filter`, `$select`, `$orderby`, `$top`, `$skip`, `$count`.
+
+### 1. List All Indicators
+
+```
+GET /Indicator
+```
+
+**Example:**
+```
+https://ghoapi.azureedge.net/api/Indicator
+```
+
+**Response:**
+```json
+{
+  "@odata.context": "...",
+  "value": [
+    {
+      "IndicatorCode": "WHOSIS_000001",
+      "IndicatorName": "Life expectancy at birth (years)",
+      "Language": "EN"
+    },
+    {
+      "IndicatorCode": "WHOSIS_000002",
+      "IndicatorName": "Healthy life expectancy (HALE) at birth (years)",
+      "Language": "EN"
+    },
+    {
+      "IndicatorCode": "WHS4_100",
+      "IndicatorName": "Measles (MCV1) immunization coverage among 1-year-olds (%)",
+      "Language": "EN"
+    }
+  ]
+}
+```
+
+### 2. Get Data for a Specific Indicator
+
+```
+GET /{IndicatorCode}
+```
+
+**Example (life expectancy at birth):**
+```
+https://ghoapi.azureedge.net/api/WHOSIS_000001
+```
+
+**Response:**
+```json
+{
+  "@odata.context": "...",
+  "value": [
+    {
+      "Id": 12345,
+      "IndicatorCode": "WHOSIS_000001",
+      "SpatialDim": "USA",
+      "SpatialDimType": "COUNTRY",
+      "TimeDim": 2019,
+      "TimeDimType": "YEAR",
+      "Dim1": "SEX",
+      "Dim1Type": "BTSX",
+      "Dim2": null,
+      "Dim2Type": null,
+      "Dim3": null,
+      "Dim3Type": null,
+      "DataSourceDim": null,
+      "Value": "78.5",
+      "NumericValue": 78.5,
+      "Low": 78.2,
+      "High": 78.8,
+      "Comments": "",
+      "Date": "2024-01-15T00:00:00+00:00",
+      "TimeDimensionValue": "2019",
+      "TimeDimensionBegin": "2019-01-01T00:00:00+00:00",
+      "TimeDimensionEnd": "2019-12-31T00:00:00+00:00"
+    }
+  ]
+}
+```
+
+### 3. Filter by Country
+
+Use OData `$filter` to restrict results by country (SpatialDim).
+
+**Example (life expectancy for USA only):**
+```
+https://ghoapi.azureedge.net/api/WHOSIS_000001?$filter=SpatialDim eq 'USA'
+```
+
+**Example (life expectancy for multiple countries):**
+```
+https://ghoapi.azureedge.net/api/WHOSIS_000001?$filter=SpatialDim eq 'USA' or SpatialDim eq 'GBR' or SpatialDim eq 'JPN'
+```
+
+### 4. Filter by Year
+
+**Example (life expectancy in 2019):**
+```
+https://ghoapi.azureedge.net/api/WHOSIS_000001?$filter=TimeDim eq 2019
+```
+
+**Example (life expectancy for USA since 2015):**
+```
+https://ghoapi.azureedge.net/api/WHOSIS_000001?$filter=SpatialDim eq 'USA' and TimeDim ge 2015
+```
+
+### 5. Filter by Sex/Dimension
+
+**Example (life expectancy, both sexes, USA, 2015+):**
+```
+https://ghoapi.azureedge.net/api/WHOSIS_000001?$filter=SpatialDim eq 'USA' and TimeDim ge 2015 and Dim1 eq 'BTSX'
+```
+
+Dim1 sex values: `BTSX` (both sexes), `MLE` (male), `FMLE` (female).
+
+### 6. Pagination and Limiting
+
+**Example (first 10 results):**
+```
+https://ghoapi.azureedge.net/api/WHOSIS_000001?$top=10
+```
+
+**Example (skip first 100, get next 50):**
+```
+https://ghoapi.azureedge.net/api/WHOSIS_000001?$top=50&$skip=100
+```
+
+### 7. Select Specific Fields
+
+```
+https://ghoapi.azureedge.net/api/WHOSIS_000001?$filter=SpatialDim eq 'USA'&$select=SpatialDim,TimeDim,NumericValue,Dim1
+```
+
+### 8. Order Results
+
+```
+https://ghoapi.azureedge.net/api/WHOSIS_000001?$filter=SpatialDim eq 'USA'&$orderby=TimeDim desc
+```
+
+### 9. List Dimension Values
+
+```
+GET /DIMENSION/{DimensionType}/DimensionValues
+```
+
+**Example (list all countries):**
+```
+https://ghoapi.azureedge.net/api/DIMENSION/COUNTRY/DimensionValues
+```
+
+**Example (list all regions):**
+```
+https://ghoapi.azureedge.net/api/DIMENSION/REGION/DimensionValues
+```
+
+**Example (list sex dimension values):**
+```
+https://ghoapi.azureedge.net/api/DIMENSION/SEX/DimensionValues
+```
+
+---
+
+## Common Indicator Codes
+
+### Life Expectancy & Mortality
+| Code | Description |
+|------|-------------|
+| `WHOSIS_000001` | Life expectancy at birth (years) |
+| `WHOSIS_000002` | Healthy life expectancy (HALE) at birth (years) |
+| `WHOSIS_000004` | Neonatal mortality rate (per 1000 live births) |
+| `MDG_0000000001` | Infant mortality rate (per 1000 live births) |
+| `MDG_0000000007` | Under-five mortality rate (per 1000 live births) |
+| `MORT_MATERNALNUM` | Number of maternal deaths |
+| `MDG_0000000026` | Maternal mortality ratio (per 100000 live births) |
+| `NCDMORT3070` | Probability of dying from NCDs between ages 30-70 |
+| `LIFE_0000000029` | Adult mortality rate (probability of dying 15-60) |
+
+### Communicable Diseases
+| Code | Description |
+|------|-------------|
+| `WHS3_49` | HIV prevalence (% of population ages 15-49) |
+| `MDG_0000000029` | Tuberculosis incidence (per 100,000) |
+| `MALARIA_EST_INCIDENCE` | Malaria incidence (per 1000 population at risk) |
+| `WHS3_62` | New HIV infections (per 1000 uninfected population) |
+
+### Immunization
+| Code | Description |
+|------|-------------|
+| `WHS4_100` | Measles (MCV1) immunization (% of 1-year-olds) |
+| `WHS4_117` | DTP3 immunization (% of 1-year-olds) |
+| `WHS4_129` | Hepatitis B (HepB3) immunization (%) |
+| `WHS4_543` | Polio (Pol3) immunization (% of 1-year-olds) |
+
+### Non-Communicable Diseases & Risk Factors
+| Code | Description |
+|------|-------------|
+| `NCD_BMI_30A` | Prevalence of obesity (BMI >= 30), age-standardized |
+| `NCD_HYP_PREVALENCE_A` | Prevalence of raised blood pressure |
+| `NCD_GLUC_04` | Prevalence of diabetes (% of population) |
+| `M_Est_smk_curr_std` | Prevalence of current tobacco smoking |
+| `SA_0000001462` | Total alcohol per capita consumption (litres) |
+
+### Health Systems
+| Code | Description |
+|------|-------------|
+| `HWF_0001` | Medical doctors (per 10,000 population) |
+| `HWF_0006` | Nursing and midwifery personnel (per 10,000) |
+| `WHS7_104` | Hospital beds (per 10,000 population) |
+| `GHED_CHE_pc_US_SHA2011` | Current health expenditure per capita (USD) |
+| `UHC_INDEX_REPORTED` | UHC service coverage index |
+
+### Environmental Health
+| Code | Description |
+|------|-------------|
+| `SDGPM25` | PM2.5 air pollution, mean annual exposure (ug/m3) |
+| `WSH_SANITATION_SAFELY_MANAGED` | Safely managed sanitation services (%) |
+| `WSH_WATER_SAFELY_MANAGED` | Safely managed drinking water services (%) |
+
+---
+
+## Country Codes (ISO 3166-1 alpha-3)
+
+The GHO API uses **ISO 3-letter codes** for countries in the `SpatialDim` field.
+
+`USA` (United States), `GBR` (United Kingdom), `DEU` (Germany), `FRA` (France), `JPN` (Japan), `CHN` (China), `IND` (India), `BRA` (Brazil), `ZAF` (South Africa), `NGA` (Nigeria), `AUS` (Australia), `CAN` (Canada), `KOR` (Republic of Korea), `MEX` (Mexico), `RUS` (Russian Federation)
+
+WHO Regions: `AFR` (Africa), `AMR` (Americas), `SEAR` (South-East Asia), `EUR` (Europe), `EMR` (Eastern Mediterranean), `WPR` (Western Pacific), `GLOBAL` (Global)
+
+---
+
+## Response Format
+All responses are JSON following OData v4 conventions:
+
+```json
+{
+  "@odata.context": "https://ghoapi.azureedge.net/api/$metadata#...",
+  "value": [
+    { ... observation object ... },
+    { ... observation object ... }
+  ]
+}
+```
+
+Key fields in each observation:
+- `SpatialDim`: Country/region code (ISO alpha-3)
+- `TimeDim`: Year (integer)
+- `NumericValue`: The numeric data value (float or null)
+- `Value`: String representation of the value
+- `Low` / `High`: Confidence interval bounds (when available)
+- `Dim1`: First additional dimension (often sex: `BTSX`, `MLE`, `FMLE`)
+- `Dim2`, `Dim3`: Additional dimensions (age group, etc.)
+
+## Notes
+- The API uses OData v4 syntax. Filter operators: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `and`, `or`, `not`. String values must be in single quotes.
+- Not all indicators have data for all countries or years. Check data availability before building dependent workflows.
+- `NumericValue` is preferred over `Value` for numeric analysis; `Value` is a string and may contain qualifiers.
+- Many indicators are disaggregated by sex (`Dim1`) and/or age group (`Dim2`). Use the dimension values endpoint to discover valid codes.
+- Data may have multi-year lag, especially for lower-income countries.
+- The `Low` and `High` fields provide uncertainty intervals from WHO estimation processes (not all indicators have these).
+- For bulk exploration, the GHO data portal at https://www.who.int/data/gho provides a browsable interface to find indicator codes.

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

@@ -0,0 +1,239 @@
+# World Bank Open Data API
+
+## Base URL
+
+```
+https://api.worldbank.org/v2
+```
+
+## Authentication
+
+**No API key required.** The API is fully open.
+
+## Key Endpoints
+
+### 1. Get Indicator Data for a Country
+```
+GET /country/{country_code}/indicator/{indicator_code}
+```
+| Parameter | Required | Description                                        |
+|-----------|----------|----------------------------------------------------|
+| format    | No       | `json`, `xml` (default), `jsonP`                  |
+| date      | No       | Year range: `2010:2023`, single year: `2020`       |
+| page      | No       | Page number (default 1)                            |
+| per_page  | No       | Results per page (default 50, max 32500)           |
+| MRV       | No       | Most recent values: number of recent data points   |
+| gapfill   | No       | `Y` to fill gaps with most recent value            |
+| frequency | No       | `M` (monthly), `Q` (quarterly), `Y` (yearly)      |
+| source    | No       | Source ID number                                   |
+
+Example (GDP for USA, 2015-2023):
+```
+https://api.worldbank.org/v2/country/US/indicator/NY.GDP.MKTP.CD?format=json&date=2015:2023
+```
+
+Example (most recent 5 values):
+```
+https://api.worldbank.org/v2/country/US/indicator/NY.GDP.MKTP.CD?format=json&MRV=5
+```
+
+### 2. Get Indicator Data for Multiple Countries
+```
+GET /country/{code1};{code2};{code3}/indicator/{indicator_code}
+```
+Example:
+```
+https://api.worldbank.org/v2/country/US;GB;CN;IN/indicator/SP.POP.TOTL?format=json&date=2020:2023
+```
+
+### 3. Get Indicator Data for All Countries
+```
+GET /country/all/indicator/{indicator_code}
+```
+Example:
+```
+https://api.worldbank.org/v2/country/all/indicator/SI.POV.DDAY?format=json&date=2020&per_page=300
+```
+
+### 4. Get Indicator Data by Region/Income Group
+```
+GET /country/{aggregate_code}/indicator/{indicator_code}
+```
+Aggregate codes: `EAS` (East Asia), `ECS` (Europe & Central Asia), `LIC` (Low Income), `HIC` (High Income), `WLD` (World), etc.
+
+Example:
+```
+https://api.worldbank.org/v2/country/WLD/indicator/NY.GDP.MKTP.CD?format=json&date=2020:2023
+```
+
+### 5. List All Countries
+```
+GET /country
+```
+Example:
+```
+https://api.worldbank.org/v2/country?format=json&per_page=300
+```
+
+### 6. Get Country Info
+```
+GET /country/{country_code}
+```
+Example:
+```
+https://api.worldbank.org/v2/country/US?format=json
+```
+
+### 7. List All Indicators
+```
+GET /indicator
+```
+Example:
+```
+https://api.worldbank.org/v2/indicator?format=json&per_page=100
+```
+
+### 8. Search Indicators
+```
+GET /indicator
+```
+Use the query string directly in the URL path or filter by topic/source.
+
+By topic:
+```
+https://api.worldbank.org/v2/topic/3/indicator?format=json
+```
+
+By source:
+```
+https://api.worldbank.org/v2/source/2/indicator?format=json&per_page=50
+```
+
+### 9. List Topics
+```
+GET /topic
+```
+Example:
+```
+https://api.worldbank.org/v2/topic?format=json
+```
+
+### 10. List Sources
+```
+GET /source
+```
+Example:
+```
+https://api.worldbank.org/v2/source?format=json
+```
+
+## Common Indicator Codes
+
+| Indicator Code         | Description                                     |
+|------------------------|-------------------------------------------------|
+| NY.GDP.MKTP.CD        | GDP (current US$)                               |
+| NY.GDP.MKTP.KD.ZG     | GDP growth (annual %)                           |
+| NY.GDP.PCAP.CD        | GDP per capita (current US$)                    |
+| NY.GDP.PCAP.PP.CD     | GDP per capita, PPP (current intl $)            |
+| SP.POP.TOTL           | Population, total                               |
+| SP.POP.GROW           | Population growth (annual %)                    |
+| SP.DYN.LE00.IN        | Life expectancy at birth (years)                |
+| SP.DYN.TFRT.IN        | Fertility rate (births per woman)               |
+| SL.UEM.TOTL.ZS        | Unemployment (% of total labor force)           |
+| FP.CPI.TOTL.ZG        | Inflation, consumer prices (annual %)           |
+| SI.POV.DDAY           | Poverty headcount at $2.15/day (% of pop)       |
+| SI.POV.GINI           | Gini index                                      |
+| BX.KLT.DINV.CD.WD     | Foreign direct investment, net inflows (BoP, US$)|
+| NE.EXP.GNFS.ZS        | Exports of goods and services (% of GDP)        |
+| EN.ATM.CO2E.PC        | CO2 emissions (metric tons per capita)          |
+| SE.ADT.LITR.ZS        | Literacy rate, adult (% ages 15+)               |
+| SH.XPD.CHEX.PC.CD     | Current health expenditure per capita (US$)     |
+| IT.NET.USER.ZS        | Individuals using the Internet (% of pop)       |
+
+## Common Country Codes (ISO 3166-1 alpha-2)
+
+`US` (USA), `GB` (UK), `CN` (China), `IN` (India), `JP` (Japan), `DE` (Germany), `FR` (France), `BR` (Brazil), `ZA` (South Africa), `NG` (Nigeria), `AU` (Australia), `CA` (Canada)
+
+## Response Format
+
+**Important:** JSON responses are returned as a **two-element array**. The first element is pagination metadata; the second is the data array.
+
+### Indicator observations
+```json
+[
+  {
+    "page": 1,
+    "pages": 1,
+    "per_page": 50,
+    "total": 9,
+    "sourceid": "2",
+    "lastupdated": "2024-03-28"
+  },
+  [
+    {
+      "indicator": {
+        "id": "NY.GDP.MKTP.CD",
+        "value": "GDP (current US$)"
+      },
+      "country": {
+        "id": "US",
+        "value": "United States"
+      },
+      "countryiso3code": "USA",
+      "date": "2023",
+      "value": 27360935000000,
+      "unit": "",
+      "obs_status": "",
+      "decimal": 0
+    },
+    {
+      "indicator": { "id": "NY.GDP.MKTP.CD", "value": "GDP (current US$)" },
+      "country": { "id": "US", "value": "United States" },
+      "countryiso3code": "USA",
+      "date": "2022",
+      "value": 25462700000000,
+      "unit": "",
+      "obs_status": "",
+      "decimal": 0
+    }
+  ]
+]
+```
+
+Note: `value` is `null` when data is unavailable for that year.
+
+### Country info
+```json
+[
+  { "page": 1, "pages": 1, "per_page": 50, "total": 1 },
+  [
+    {
+      "id": "US",
+      "iso2Code": "US",
+      "name": "United States",
+      "region": { "id": "NAC", "iso2code": "XU", "value": "North America" },
+      "adminregion": { "id": "", "iso2code": "", "value": "" },
+      "incomeLevel": { "id": "HIC", "iso2code": "XD", "value": "High income" },
+      "lendingType": { "id": "LNX", "iso2code": "XX", "value": "Not classified" },
+      "capitalCity": "Washington D.C.",
+      "longitude": "-77.032",
+      "latitude": "38.8895"
+    }
+  ]
+]
+```
+
+## Rate Limits
+
+- No formal rate limits published; the API is open and generous.
+- For bulk downloads, use `per_page=32500` to minimize requests.
+- Be respectful: 1-2 requests/second for automated scripts.
+- For very large datasets, consider the World Bank bulk download facility.
+
+## Notes
+
+- Always include `format=json` -- the default is XML.
+- Results are returned in **descending** date order by default.
+- `null` values are common for recent years (data not yet published) or for indicators with sparse coverage.
+- Pagination: check `pages` in the metadata; iterate `page=1`, `page=2`, etc.
+- Country codes follow ISO 3166-1 alpha-2 (2-letter) in the URL path. The response also includes `countryiso3code`.