AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

database-lookup

Queries documented public database APIs with explicit endpoints, filters, pagination, and provenance. Used when a scientific, regulatory, financial, or other database-backed fact must be retrieved reproducibly from a named source rather than inferred from general knowledge.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--database-lookup at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 83

references/bls.md

Bureau of Labor Statistics (BLS) Public Data API

Base URL

https://api.bls.gov/publicAPI/v2

Version 1 (no key): https://api.bls.gov/publicAPI/v1

Authentication

API key optional but strongly recommended. Register at https://data.bls.gov/registrationEngine/

  • V1 (no key): Limited to 25 requests/day, 10-year date range, 25 series per query.
  • V2 (with key): 500 requests/day, 20-year date range, 50 series per query, plus catalog data and calculations.

Key Endpoints

1. Get Series Data (POST -- primary method)

POST /timeseries/data/

Content-Type: application/json

Request body:

{
  "seriesid": ["CUUR0000SA0", "LNS14000000"],
  "startyear": "2020",
  "endyear": "2024",
  "registrationkey": "YOUR_KEY",
  "catalog": true,
  "calculations": true,
  "annualaverage": true,
  "aspects": true
}

| Field | Required | V1 | V2 | Description | |------------------|----------|-----|-----|------------------------------------------------------| | seriesid | Yes | Yes | Yes | Array of series IDs (max 25 v1 / 50 v2) | | startyear | No | Yes | Yes | 4-digit start year | | endyear | No | Yes | Yes | 4-digit end year | | registrationkey | No | No | Yes | API key (required for v2 features) | | catalog | No | No | Yes | true to include series metadata | | calculations | No | No | Yes | true to include net/pct changes | | annualaverage | No | No | Yes | true to include annual averages | | aspects | No | No | Yes | true to include footnotes and aspects |

2. Get Single Series Data (GET -- convenience)

GET /timeseries/data/{seriesID}

Example:

https://api.bls.gov/publicAPI/v2/timeseries/data/CUUR0000SA0?registrationkey=YOUR_KEY&startyear=2022&endyear=2024

3. Latest Data (GET -- no date range)

GET /timeseries/data/{seriesID}

Without startyear/endyear, returns the most recent 3 years.

Example:

https://api.bls.gov/publicAPI/v2/timeseries/data/LNS14000000?registrationkey=YOUR_KEY

Common Series IDs

Consumer Price Index (CPI)

| Series ID | Description | |-----------------|---------------------------------------------------| | CUUR0000SA0 | CPI-U All Items, US City Avg, Not Seasonally Adj | | CUSR0000SA0 | CPI-U All Items, US City Avg, Seasonally Adj | | CUUR0000SAF1 | CPI-U Food, US City Avg | | CUUR0000SETB01 | CPI-U Gasoline (all types) | | CUUR0000SAH1 | CPI-U Shelter | | CUUR0000SAM | CPI-U Medical Care |

CPI series ID structure: CU + U/S (unadj/adj) + R/S (revision) + area code + item code

Employment / Unemployment (Current Population Survey)

| Series ID | Description | |-----------------|---------------------------------------------------| | LNS14000000 | Unemployment Rate (seasonally adjusted) | | LNS11000000 | Civilian Labor Force Level | | LNS12000000 | Employment Level | | LNS13000000 | Unemployment Level | | LNS14000006 | Unemployment Rate - Black or African American | | LNS14000009 | Unemployment Rate - Hispanic or Latino |

Employment (Current Employment Statistics / Nonfarm Payrolls)

| Series ID | Description | |-----------------|---------------------------------------------------| | CES0000000001 | Total Nonfarm Employment (seasonally adj) | | CES0500000003 | Average Hourly Earnings, Total Private | | CES0500000002 | Average Weekly Hours, Total Private |

Producer Price Index (PPI)

| Series ID | Description | |-----------------|---------------------------------------------------| | WPSFD4 | PPI Final Demand | | WPUFD49104 | PPI Final Demand less Foods & Energy |

Employment Cost Index (ECI)

| Series ID | Description | |-----------------|---------------------------------------------------| | CIU1010000000000A | ECI Total Compensation, All Civilians |

Occupational Employment & Wage Statistics (OEWS)

| Series ID Pattern | Description | |-------------------|-------------------------------------------------| | OEUM003342000000011-0000 | Example: specific occupation/area combo |

OEWS series IDs are complex. Use the BLS Series ID finder: https://data.bls.gov/cgi-bin/srgate

Series ID Structure

BLS series IDs encode survey, seasonal adjustment, area, industry, and item information. Key survey prefixes:

| Prefix | Survey | |--------|------------------------------------------------| | CU | Consumer Price Index | | LN | Current Population Survey (Labor Force) | | CE | Current Employment Statistics | | WP | Producer Price Index | | CI | Employment Cost Index / National Compensation | | OE | Occupational Employment & Wage Statistics | | LA | Local Area Unemployment Statistics | | SM | State and Metro Area Employment (CES) | | JT | Job Openings and Labor Turnover (JOLTS) |

Response Format

Standard response

{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 85,
  "message": [],
  "Results": {
    "series": [
      {
        "seriesID": "CUUR0000SA0",
        "catalog": {
          "series_title": "All items in U.S. city average, all urban consumers, not seasonally adjusted",
          "series_id": "CUUR0000SA0",
          "seasonality": "Not Seasonally Adjusted",
          "survey_name": "Consumer Price Index - All Urban Consumers",
          "survey_abbreviation": "CU",
          "measure_data_type": "All items",
          "area": "U.S. city average",
          "item": "All items"
        },
        "data": [
          {
            "year": "2024",
            "period": "M01",
            "periodName": "January",
            "latest": "true",
            "value": "308.417",
            "footnotes": [{}],
            "calculations": {
              "net_changes": {
                "1": "0.5",
                "3": "1.2",
                "6": "2.1",
                "12": "3.1"
              },
              "pct_changes": {
                "1": "0.2",
                "3": "0.4",
                "6": "0.7",
                "12": "3.1"
              }
            }
          },
          {
            "year": "2023",
            "period": "M12",
            "periodName": "December",
            "value": "306.746",
            "footnotes": [{}]
          }
        ]
      }
    ]
  }
}

Key fields in data objects

  • year: 4-digit year string
  • period: M01-M12 (monthly), Q01-Q05 (quarterly), A01 (annual), S01-S03 (semi-annual)
  • periodName: Human-readable period name
  • value: String (convert to float for calculations)
  • latest: "true" on the most recent observation only
  • calculations: Only present when calculations: true in request (V2). Contains net_changes and pct_changes over 1, 3, 6, 12 month spans.
  • footnotes: Array of footnote objects

Error response

{
  "status": "REQUEST_NOT_PROCESSED",
  "responseTime": 10,
  "message": ["No data available for the given series and date range."],
  "Results": {
    "series": []
  }
}

Rate Limits

| Feature | V1 (no key) | V2 (with key) | |---------------------|-----------------|------------------| | Daily query limit | 25 requests | 500 requests | | Series per query | 25 | 50 | | Years per query | 10 | 20 | | Catalog data | No | Yes | | Calculations | No | Yes | | Annual averages | No | Yes | | Net/pct changes | No | Yes |

Notes

  • BLS strongly prefers POST requests for data retrieval. The GET endpoint is a convenience wrapper.
  • Period M13 represents the annual average (only present when annualaverage: true).
  • All value fields are strings. Missing data is typically omitted (the observation simply won't appear).
  • For CPI percent change (inflation rate), you can either calculate from raw index values or use the V2 calculations feature which provides pre-computed 12-month percent changes.
  • The BLS website has a Series ID finder tool for constructing IDs: https://data.bls.gov/cgi-bin/srgate
  • Bulk data is available for download at https://download.bls.gov/pub/time.series/ organized by survey prefix.