KosmoKrator

data

US Census Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the US Census KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.us_census.*. Use lua_read_doc("integrations.us-census") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic US Census workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.us_census.list_datasets({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("us-census"))' --json
kosmo integrations:lua --eval 'print(docs.read("us-census.list_datasets"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local us_census = app.integrations.us_census
local result = us_census.list_datasets({})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.us_census, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.us_census.default.* or app.integrations.us_census.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need US Census, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

US Census

Namespace: us-census

Use this integration to discover U.S. Census Data API datasets, inspect dataset metadata, find variables and geographies, view official examples, and run data queries.

Authentication

The Census Data API is public. An api_key is optional; configure it when you need higher allowed usage. The public API guide notes a 50-variable limit per query and public unauthenticated rate limits.

Tools

  • us_census_list_datasets: search the global data.json dataset catalog.
  • us_census_dataset_metadata: get root metadata for one dataset path.
  • us_census_variables: list or search variables, optionally inside a group.
  • us_census_groups: list or search variable groups.
  • us_census_geographies: list supported geographies.
  • us_census_examples: fetch official example queries.
  • us_census_data_query: query data and normalize rows into records.
  • us_census_data_query_url: build a shareable data query URL.

Dataset Paths

Use dataset paths without /data, for example:

  • 2023/acs/acs5
  • 2023/acs/acs1/profile
  • 2020/dec/pl

Examples

local variables = tools.us_census_variables({
  dataset = "2023/acs/acs5",
  q = "median household income",
  limit = 10
})

local rows = tools.us_census_data_query({
  dataset = "2023/acs/acs5",
  get = "NAME,B19013_001E",
  ["for"] = "state:*"
})

local counties = tools.us_census_data_query({
  dataset = "2023/acs/acs5",
  get = "NAME,B01001_001E",
  ["for"] = "county:*",
  ["in"] = "state:06"
})
Raw agent markdown 
# US Census

Namespace: `us-census`

Use this integration to discover U.S. Census Data API datasets, inspect dataset
metadata, find variables and geographies, view official examples, and run data
queries.

## Authentication

The Census Data API is public. An `api_key` is optional; configure it when you
need higher allowed usage. The public API guide notes a 50-variable limit per
query and public unauthenticated rate limits.

## Tools

- `us_census_list_datasets`: search the global `data.json` dataset catalog.
- `us_census_dataset_metadata`: get root metadata for one dataset path.
- `us_census_variables`: list or search variables, optionally inside a group.
- `us_census_groups`: list or search variable groups.
- `us_census_geographies`: list supported geographies.
- `us_census_examples`: fetch official example queries.
- `us_census_data_query`: query data and normalize rows into records.
- `us_census_data_query_url`: build a shareable data query URL.

## Dataset Paths

Use dataset paths without `/data`, for example:

- `2023/acs/acs5`
- `2023/acs/acs1/profile`
- `2020/dec/pl`

## Examples

```lua
local variables = tools.us_census_variables({
  dataset = "2023/acs/acs5",
  q = "median household income",
  limit = 10
})

local rows = tools.us_census_data_query({
  dataset = "2023/acs/acs5",
  get = "NAME,B19013_001E",
  ["for"] = "state:*"
})

local counties = tools.us_census_data_query({
  dataset = "2023/acs/acs5",
  get = "NAME,B01001_001E",
  ["for"] = "county:*",
  ["in"] = "state:06"
})
```
Metadata-derived Lua example 
local result = app.integrations.us_census.list_datasets({})
print(result)

Functions

list_datasets Read

List and search Census API datasets.

Lua path
app.integrations.us_census.list_datasets
Full name
us-census.us_census_list_datasets
ParameterTypeRequiredDescription
No parameters.
dataset_metadata Read

Get root metadata for one Census API dataset.

Lua path
app.integrations.us_census.dataset_metadata
Full name
us-census.us_census_dataset_metadata
ParameterTypeRequiredDescription
No parameters.
variables Read

List or search dataset variables.

Lua path
app.integrations.us_census.variables
Full name
us-census.us_census_variables
ParameterTypeRequiredDescription
No parameters.
groups Read

List or search dataset variable groups.

Lua path
app.integrations.us_census.groups
Full name
us-census.us_census_groups
ParameterTypeRequiredDescription
No parameters.
geographies Read

List supported geographies for a dataset.

Lua path
app.integrations.us_census.geographies
Full name
us-census.us_census_geographies
ParameterTypeRequiredDescription
No parameters.
examples Read

Get example queries for a dataset.

Lua path
app.integrations.us_census.examples
Full name
us-census.us_census_examples
ParameterTypeRequiredDescription
No parameters.
data_query Read

Query a Census dataset and normalize rows into records.

Lua path
app.integrations.us_census.data_query
Full name
us-census.us_census_data_query
ParameterTypeRequiredDescription
No parameters.
data_query_url Read

Build a Census data query URL for sharing or inspection.

Lua path
app.integrations.us_census.data_query_url
Full name
us-census.us_census_data_query_url
ParameterTypeRequiredDescription
No parameters.