Loading data
Data API
Retrieve public BBER data for research, classroom work, and applied analysis. Use metadata to discover tables and fields, then request observations with explicit geography, estimate type, and time filters.
Public REST requests use HTTP GET and return JSON. Website Download menus provide API links, JSON files, and CSV ZIPs.
https://api.bber.unm.edu/api/data/rest/bbertable
Use the REST endpoint to request a table, limit the returned variables when needed, and filter observations by geography, time period, and other supported dimensions.
https://api.bber.unm.edu/api/data/rest/bbertableMetadata requests are useful for discovering available tables, variables, and valid filter values before scripting a query.
https://api.bber.unm.edu/api/data/rest/metadata?api=tablevalues&table=b01001&stfips=35&areatype=01&variables=stfips%2Careatype%2Cperiodyear%2CperiodtypeThe parameters below are commonly used across BBER REST datasets. Available fields can vary by table, so confirm table-level metadata before building production scripts.
| Parameter | Description | Sample Values |
|---|---|---|
| table | Public table name from the metadata catalog. Joined requests use a quoted comma-separated list. | b01001, qcew; "b01001,b01002" |
| variables | Columns to return. Use table.column for measurements from joined tables. Shared geography and time identifiers accompany the selected measurements. | total_e; b01001.total_e,b01002.medianage_total_e |
| stfips | State code. Preserve leading zeros by keeping codes as strings. | 35 |
| areatype | Geography type. Discover the types supported by the chosen table. | 01 (state), 04 (county), 20 (place) |
| area | Geographic area identifier from metadata. Preserve the six-character code, including leading zeros. | 000000, 000001 |
| periodtype | Observation or estimate type. ACS 61 is a 1-year estimate; 60 is a 5-year estimate. Explicit multiple types share a common latest year. | 61; 60; "60,61" |
| periodyear | A year, numeric range, selected years, or latest. latest chooses the newest year matching every other row filter. | latest; 2020-2024; "latest,2020" |
| period | Month, quarter, or other within-year period. Codes vary by table; latest does not choose this period for you. | 00, 01, 02 |
| indcode | Industry code, where supported. Keep codes as strings. | 00, 23 |
| adjusted | Seasonal adjustment flag, where supported. Consult table metadata. | 0, 1 |
| ownership | Ownership identifier for supported labor-market datasets. | 00, 50 |
| prelim | Preliminary/publication flag, where supported. It also constrains latest-year resolution. | 0, 1 |
| api | Metadata operation. tablevalues discovers filter values; tablevariables lists columns; variabledetails describes measurements; tables lists public datasets. | tablevalues, tablevariables, variabledetails, tables |
Use periodyear=latest for a current-year snapshot without maintaining a hardcoded year.
All other row filters apply before the year is selected: geography, period type, industry, ownership, period, seasonal adjustment, and preliminary status. Without a periodtype filter, latest selects the newest matching year across available types.
Latest selects a year, not the latest month or quarter. It may return several observations within that year. Select or compare matching months or quarters separately.
For an explicit list of period types, latest selects the newest year represented by every requested type. ACS periodtype=61 means 1-year estimates; periodtype=60 means 5-year estimates. A 5-year estimate's periodyear is its ending year, so an ending year of 2024 describes 2020–2024.
For example, if a table's 1-year data ends in 2025 and its 5-year data ends in 2024, requesting 61 selects 2025, requesting 60 selects 2024, and requesting both selects 2024. Availability depends on the selected table and filters, not the current calendar year.
https://api.bber.unm.edu/api/data/rest/bbertable?table=b01001&stfips=35&areatype=01&periodtype=61&periodyear=latesthttps://api.bber.unm.edu/api/data/rest/bbertable?table=b01001&stfips=35&areatype=01&periodtype=60&periodyear=latesthttps://api.bber.unm.edu/api/data/rest/bbertable?table=b01001&stfips=35&areatype=01&periodtype=%2260%2C61%22&periodyear=latestResolve latest separately when a comparison needs to distinguish it from explicitly requested years.
You can combine latest with explicit years or numeric ranges. Duplicate years appear once: latest,2025 returns one year if latest resolves to 2025, and two years if it later resolves to 2026. A mixed response does not reliably identify the resolved latest year.
Explicit years may still return observations when no common latest year exists. Do not assume that the maximum year in a mixed response is the year latest selected.
For one table, resolve the year with metadata api=tablevalues and variables=periodyear. This endpoint returns an array of year objects, not the bbertable envelope. Keep every relevant row filter identical, then request the resolved numeric year plus the baseline. An empty year array means there is no matching latest year.
For joined tables, use a latest-only bbertable request to resolve the year from actual matching joined rows. Gaps matter: the common year is not simply the smaller of the tables' maximum years. Then request numeric comparison years with the same join and filters.
Build rolling history the same way: resolve latest, then send a numeric range. The expression 2020-latest is unsupported. Separate requests can resolve to different years; align years explicitly when multiple charts need one comparison period.
https://api.bber.unm.edu/api/data/rest/bbertable?table=b01001&stfips=35&areatype=01&periodtype=%2260%2C61%22&periodyear=%22latest%2C2020%22https://api.bber.unm.edu/api/data/rest/metadata?api=tablevalues&table=b01001&stfips=35&areatype=01&periodtype=%2260%2C61%22&periodyear=latest&variables=periodyear[
{ "periodyear": "2024" }
]https://api.bber.unm.edu/api/data/rest/bbertable?table=b01001&stfips=35&areatype=01&periodtype=%2260%2C61%22&periodyear=%222024%2C2020%22Successful tabular responses contain metadata and a data array. Missing observations must remain distinguishable from zero.
Read observations from response.data. Year values are strings; convert them only when numeric sorting or arithmetic is needed. There is no resolvedLatestYear field. Derive titles, legends, tooltips, and comparison dates from the returned observations.
Latest does not guarantee that every requested geography has a row or that every measurement is populated. Empty data arrays and null values are valid outcomes. A published zero is a value; a null or suppressed measurement is unavailable. Do not convert null with Number(null), which produces zero, or silently substitute an older observation.
Use metadata.columns to check column names, measurement units, descriptions, and estimate/margin pairs. A column can exist while its values are null; inspect the actual returned measurements before deciding that an entire series is unavailable. Metadata update dates are not observation years.
Calculate changes in your script or application. Match observations by geography, estimate type, industry, ownership, and the same month or quarter where applicable. Never pair rows by array position or mix ACS 1-year and 5-year estimates into a single annual series.
If the baseline is absent, latest equals the baseline, or a percentage-change denominator is zero, report unavailable or no distinct comparison period. For interactive applications, cancel or ignore obsolete requests after filter changes and include all filters in cache keys.
Keep requests scoped and handle unsuccessful responses before reading data.
Responses involving latest have a fixed five-minute server cache lifetime and a one-minute HTTP cache lifetime. Refetching can still return cached data. Use bounded client cache freshness and normal refetch behavior.
Do not routinely append refresh=true. It triggers backend cache-refresh work for the table rather than guaranteeing an inexpensive fresh read.
The default result cap is 10,000 rows. A numeric range can expand to at most 50 values, and a parameter can contain at most 200 values after expansion. Select geography, period type, years, and measurement columns to keep requests manageable; do not assume a capped response is a complete table.
Use URLSearchParams or your HTTP client query builder. Preserve leading zeros in codes. For comma-separated filter or table selections, the examples use quoted lists; %22 is a double quote and %2C is a comma in the encoded URL.
Check the HTTP status before parsing a success envelope. Invalid tables, unsupported inputs, and unsupported latest requests can return HTTP 400; server failures can return HTTP 500. Error bodies may be plain text rather than JSON. Retain a readable error state and do not interpret an error as an empty dataset.
These public REST endpoints return JSON. This website's Download menus also package CSV files and metadata for research use; CSV ZIP downloads are website routes, not an undocumented format parameter on bbertable.
Latest is available on tabular reads, table-value metadata, and maps with an explicit data table.
bbertable returns the metadata/data envelope, including joined-table queries. metadata?api=tablevalues returns an array of filter-value objects; variables=periodyear can resolve the latest matching year for one table.
makemap returns GeoJSON features and metadata. With an explicit data table it supports latest. A map-only boundary request without a data table does not support latest.
cpitab is the CPI presentation-table endpoint and does not support latest. Use bbertable with the CPI data table when filtering CPI observations by year.
Use metadata?api=tables for the current public catalog, tablevariables for column names, and variabledetails for measurement descriptions. Table schemas and coverage can change; discover them from the API rather than assuming another dataset's fields.
https://api.bber.unm.edu/api/data/rest/makemap?table=b01001&stfips=35&areatype=04&area=000001&periodtype=60&periodyear=latesthttps://api.bber.unm.edu/api/data/rest/cpitabThe periodyear parameter accepts latest, numeric ranges, and comma-separated selections. These examples request fixed historical years.
https://api.bber.unm.edu/api/data/rest/bbertable?table=b01001&stfips=35&areatype=01&periodtype=60&periodyear=2020-2024https://api.bber.unm.edu/api/data/rest/bbertable?table=b01001&stfips=35&areatype=01&periodtype=60&periodyear=%222015-2017%2C2020-2024%22https://api.bber.unm.edu/api/data/rest/bbertable?table=b01001&stfips=35&areatype=01&periodtype=60&periodyear=%222020%2C2024%22When requesting multiple tables together, specify variables as `TABLENAME.VARIABLENAME` to distinguish fields cleanly and preserve a usable merged response.
https://api.bber.unm.edu/api/data/rest/bbertable?table=%22b01001%2Cb01002%22&stfips=35&areatype=01&periodtype=60&periodyear=latest&variables=b01001.total_e%2Cb01002.medianage_total_eMerged results align on shared geography and time identifiers. Both tables must have matching rows, including compatible period types. Latest is resolved from those actual joined rows.
API responses are returned in JSON with data rows and descriptive metadata packaged together.
{
"metadata": {
"columns": [],
"table": {}
},
"data": [
{
"periodyear": "2024",
"periodtype": "60",
"total_e": null
}
]
}data: the observation rows returned for the request.
metadata.columns: field-level descriptions and display labels.
metadata.table: source-level information such as title, release timing, and update date.
Use the map endpoint for GEOJSON output and the metadata endpoint to inspect available tables, variables, and values before building a request.
https://api.bber.unm.edu/api/data/rest/makemaphttps://api.bber.unm.edu/api/data/rest/metadata?api=tableshttps://api.bber.unm.edu/api/data/rest/metadata?api=tablevariables&table=b01001https://api.bber.unm.edu/api/data/rest/metadata?api=variabledetails&table=b01001https://api.bber.unm.edu/api/data/rest/metadata?api=tablevalues&table=b01001&stfips=35&areatype=01&periodtype=60&variables=periodyear%2Carea