Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to U.S. Census Bureau

Scalekit connector
Open markdown

The U.S. Census Bureau connector lets your AI agent act in each user's U.S. Census Bureau account. Each user connects their own U.S. Census Bureau API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 13 tools.

Tools
13
What they doRead · write · destructive
13 · 0 · 013 read0 write0 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the U.S. Census Bureau connection

    In AgentKit > Connections, create an U.S. Census Bureau connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'censusbureau'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize U.S. Census Bureau:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'censusbureau_timeseries_datasets_list',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their U.S. Census Bureau credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • censusbureau_data_queryQuery statistics from a dataset whose path has two segments, such as acs/acs5, acs/acs1, dec/pl, dec/dhc or pep/population, for a set of variables and geographies.Read-only

    Query Dataset (Two-Segment Path)

    Query statistics from a dataset whose path has two segments, such as acs/acs5, acs/acs1, dec/pl, dec/dhc or pep/population, for a set of variables and geographies. Returns a JSON array of rows: the first row holds the column names (the requested variables, then the geography codes) and each following row one geography's values as strings. Use this for most ACS and decennial queries. Use censusbureau_data_query_table_type for acs/acs5/subject or profile tables, and censusbureau_data_query_single for cbp.

    Inputs

    datasetstringrequired
    Second segment of the dataset path. For acs/acs5 this is acs5; other examples: acs1, acsse, pl, dhc, population. Example: acs5.
    getstringrequired
    Comma-separated variables to return, at most 50, for example NAME,B01001_001E. Use group(TABLE) to return a whole table, e.g. group(B01001). Find variable names with censusbureau_variables_list or censusbureau_groups_list. Example: NAME,B01001_001E.
    programstringrequired
    First segment of the dataset path, usually the survey program: acs (American Community Survey), dec (Decennial Census), pep (Population Estimates), abscs, cbp and so on. For acs/acs5 this is acs. Example: acs.
    yearstringrequired
    Vintage (reference year) of the dataset, as four digits. Example: 2022.
    descriptiveboolean
    Set to true to add a second header row with each variable's label. Example: true.
    forstring
    Geography level and codes to return, as level:code or level:* for all, e.g. state:*, state:06, county:*, place:44000. Leave empty when you use ucgid. Example: state:*.
    instring
    Parent geography that limits the for clause, e.g. state:06 to get counties in California; separate several parents with a space, e.g. state:06 county:037. Example: state:06.
    ucgidstring
    Uniform Census Geography Identifier, an alternative to for and in, e.g. 0400000US06 for California or pseudo(0400000US06$0500000) for all its counties. Example: 0400000US06.
  • censusbureau_data_query_singleQuery statistics from a dataset whose path has one segment, such as cbp (County Business Patterns), zbp or ecnbasic.Read-only

    Query Dataset (One-Segment Path)

    Query statistics from a dataset whose path has one segment, such as cbp (County Business Patterns), zbp or ecnbasic. Returns a JSON array of rows: the first row holds the column names (the requested variables, then the geography codes) and each following row one geography's values as strings. Use this for business and economic datasets. Use censusbureau_data_query for acs or dec datasets.

    Inputs

    datasetstringrequired
    Single-segment dataset name, such as cbp (County Business Patterns), zbp (ZIP Code Business Patterns) or ecnbasic (Economic Census). Example: cbp.
    getstringrequired
    Comma-separated variables to return, at most 50, for example NAME,B01001_001E. Use group(TABLE) to return a whole table, e.g. group(B01001). Find variable names with censusbureau_variables_list or censusbureau_groups_list. Example: NAME,B01001_001E.
    yearstringrequired
    Vintage (reference year) of the dataset, as four digits. Example: 2022.
    descriptiveboolean
    Set to true to add a second header row with each variable's label. Example: true.
    forstring
    Geography level and codes to return, as level:code or level:* for all, e.g. state:*, state:06, county:*, place:44000. Leave empty when you use ucgid. Example: state:*.
    instring
    Parent geography that limits the for clause, e.g. state:06 to get counties in California; separate several parents with a space, e.g. state:06 county:037. Example: state:06.
    naics2017string
    NAICS 2017 industry code predicate for business datasets, e.g. 72 for accommodation and food services. Example: 72.
    ucgidstring
    Uniform Census Geography Identifier, an alternative to for and in, e.g. 0400000US06 for California or pseudo(0400000US06$0500000) for all its counties. Example: 0400000US06.
  • censusbureau_data_query_table_typeQuery statistics from an ACS table-type dataset with a three-segment path, such as acs/acs5/subject, acs/acs1/profile or acs/acs5/cprofile.Read-only

    Query ACS Table Type

    Query statistics from an ACS table-type dataset with a three-segment path, such as acs/acs5/subject, acs/acs1/profile or acs/acs5/cprofile. Returns a JSON array of rows: the first row holds the column names (the requested variables, then the geography codes) and each following row one geography's values as strings. Use this for subject (S), data profile (DP) and comparison profile (CP) tables. Use censusbureau_data_query for detailed tables (B and C).

    Inputs

    datasetstringrequired
    Second segment of the dataset path. For acs/acs5 this is acs5; other examples: acs1, acsse, pl, dhc, population. Example: acs5.
    getstringrequired
    Comma-separated variables to return, at most 50, for example NAME,B01001_001E. Use group(TABLE) to return a whole table, e.g. group(B01001). Find variable names with censusbureau_variables_list or censusbureau_groups_list. Example: NAME,B01001_001E.
    programstringrequired
    First segment of the dataset path, usually the survey program: acs (American Community Survey), dec (Decennial Census), pep (Population Estimates), abscs, cbp and so on. For acs/acs5 this is acs. Example: acs.
    table_typestringrequired
    Third segment of the dataset path for ACS table types: subject, profile, cprofile or spp (for example acs/acs5/subject). Example: subject.
    yearstringrequired
    Vintage (reference year) of the dataset, as four digits. Example: 2022.
    descriptiveboolean
    Set to true to add a second header row with each variable's label. Example: true.
    forstring
    Geography level and codes to return, as level:code or level:* for all, e.g. state:*, state:06, county:*, place:44000. Leave empty when you use ucgid. Example: state:*.
    instring
    Parent geography that limits the for clause, e.g. state:06 to get counties in California; separate several parents with a space, e.g. state:06 county:037. Example: state:06.
    ucgidstring
    Uniform Census Geography Identifier, an alternative to for and in, e.g. 0400000US06 for California or pseudo(0400000US06$0500000) for all its counties. Example: 0400000US06.
  • censusbureau_datasets_listList every dataset available for one vintage (year), in DCAT catalog format.Read-only

    List Datasets for a Year

    List every dataset available for one vintage (year), in DCAT catalog format. Returns per dataset its title, description, path segments (c_dataset), vintage, and links to its variables, groups, geography and examples. Use this to find a dataset path such as acs/acs5. Use censusbureau_timeseries_datasets_list for time series.

    Inputs

    yearstringrequired
    Vintage (reference year) of the dataset, as four digits. Example: 2022.
  • censusbureau_geography_listList the geography levels of a two-segment dataset such as acs/acs5 and the parent geographies each requires.Read-only

    List Dataset Geographies

    List the geography levels of a two-segment dataset such as acs/acs5 and the parent geographies each requires. Returns per level its name (e.g. county), geo level code and the required in clause. Use this to build the for and in parameters.

    Inputs

    datasetstringrequired
    Second segment of the dataset path. For acs/acs5 this is acs5; other examples: acs1, acsse, pl, dhc, population. Example: acs5.
    programstringrequired
    First segment of the dataset path, usually the survey program: acs (American Community Survey), dec (Decennial Census), pep (Population Estimates), abscs, cbp and so on. For acs/acs5 this is acs. Example: acs.
    yearstringrequired
    Vintage (reference year) of the dataset, as four digits. Example: 2022.
  • censusbureau_group_getGet the variables of one group (table) of a two-segment dataset such as acs/acs5.Read-only

    Get Group (Table) Variables

    Get the variables of one group (table) of a two-segment dataset such as acs/acs5. Returns a variables object keyed by variable name with label, concept and predicate type. Use this to pick variables for censusbureau_data_query, or pass group(NAME) as get.

    Inputs

    datasetstringrequired
    Second segment of the dataset path. For acs/acs5 this is acs5; other examples: acs1, acsse, pl, dhc, population. Example: acs5.
    groupstringrequired
    Group (table) name, e.g. B01001. Example: B01001.
    programstringrequired
    First segment of the dataset path, usually the survey program: acs (American Community Survey), dec (Decennial Census), pep (Population Estimates), abscs, cbp and so on. For acs/acs5 this is acs. Example: acs.
    yearstringrequired
    Vintage (reference year) of the dataset, as four digits. Example: 2022.
  • censusbureau_groups_listList the groups (tables) of a two-segment dataset such as acs/acs5.Read-only

    List Dataset Groups (Tables)

    List the groups (tables) of a two-segment dataset such as acs/acs5. Returns each group's name (e.g. B01001), description and link to its variables. Use this to find a table. Use censusbureau_group_get for its variables.

    Inputs

    datasetstringrequired
    Second segment of the dataset path. For acs/acs5 this is acs5; other examples: acs1, acsse, pl, dhc, population. Example: acs5.
    programstringrequired
    First segment of the dataset path, usually the survey program: acs (American Community Survey), dec (Decennial Census), pep (Population Estimates), abscs, cbp and so on. For acs/acs5 this is acs. Example: acs.
    yearstringrequired
    Vintage (reference year) of the dataset, as four digits. Example: 2022.
  • censusbureau_table_type_group_getGet the variables of one group (table) of an ACS table-type dataset such as acs/acs5/subject.Read-only

    Get ACS Table Type Group

    Get the variables of one group (table) of an ACS table-type dataset such as acs/acs5/subject. Returns a variables object keyed by variable name with label and concept. Use this to pick variables for censusbureau_data_query_table_type.

    Inputs

    datasetstringrequired
    Second segment of the dataset path. For acs/acs5 this is acs5; other examples: acs1, acsse, pl, dhc, population. Example: acs5.
    groupstringrequired
    Group (table) name, e.g. S0101. Example: S0101.
    programstringrequired
    First segment of the dataset path, usually the survey program: acs (American Community Survey), dec (Decennial Census), pep (Population Estimates), abscs, cbp and so on. For acs/acs5 this is acs. Example: acs.
    table_typestringrequired
    Third segment of the dataset path for ACS table types: subject, profile, cprofile or spp (for example acs/acs5/subject). Example: subject.
    yearstringrequired
    Vintage (reference year) of the dataset, as four digits. Example: 2022.