U.S. flag

An official website of the United States government

Department of Labor Logo United States Department of Labor
Dot gov

The .gov means it's official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you're on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Consumer Price Index
Bureau of Labor Statistics > Consumer Price Index > Publications > Factsheets

Using CPI aspect metadata files

Starting in November 2024, the Bureau of Labor Statistics (BLS) is adding aspect metadata corresponding to CPI-U and CPI-W series in our database. The aspect metadata supplied include seasonal factors, relative importance, median standard error, 1-month and 12-month effect, and the 1-month and 12-month ‘largest or smallest change since’ historical reference. These aspect metadata provide additional information about the context and structure of CPI data and can aid users in understanding the data. Historical data back to 2012 (for some metadata aspect series) will be added in preparation for the release of 2024 end-of-year CPI metadata and 2025 seasonal factors in February 2025. These metadata will be available for months for which the associated index was published.

The added metadata series will use the aspect type codes in Table 1. below.

Table 1: CPI aspect metadata
Aspect type code Variable Name Available For Also available in Available starting from

I

 Relative importance CPI-U and CPI-W News release tables 6 and 7 (CPI-U) CPI-W table (CPI-W) March 2012

I1

 End of year relative importance CPI-U and CPI-W Relative importance table December 2020

F

 Seasonal factor CPI-U and CPI-W Seasonal factors table October 2024

H1[1,2]

 1 month 'largest/smallest since' historical reference CPI-U News release table 6 March 2012

HC

 12 month 'largest/smallest since' historical reference CPI-U News release table 7 March 2012

M1[1]

 Median standard error for 1 month percent change CPI-U News release table 6 March 2012

MC

 Median standard error for 12 month percent change CPI-U News release table 7 March 2012

V1[1,2]

 Prior 1 month percent change (corresponding to 'largest/smallest since' historical reference CPI-U News release table 6 March 2012

VC

 Prior 12 month percent change (corresponding to 'largest/smallest since' historical reference CPI-U News release table 7 March 2012

W1[1]

 1 month effect on all items CPI-U News release table 6 March 2012

WC

 12 month effect on all items CPI-U News release table 7 March 2012

Note: 1: Only available for series which have been subject to seasonal adjustment, 2: As originally issued in the publication month, metadata not subject to revision

The added aspect metadata will be accessible as flat text files for the CPI-U and CPI-W or by using the BLS public data API.

Using flat text files

The flat text files available from the BLS download page are tab-delimited text files containing an entire dataset. You can browse them online or import them to other software programs (e.g., Microsoft Excel).

To use the flat text files in Microsoft Excel:

  1. Use a web browser to go to the download page associated with the survey for which you wish to use the flat file data (for example, https://download.bls.gov/pub/time.series/cu/ for the CPI-U).

  2. Open the context menu (such as by right clicking the link) for the file you wish to work with (for example cu.aspect) and select ‘save link as’.

  3. Save the file in a location that you will be able to find, perhaps your downloads or documents folder.

  4. Open Microsoft Excel.

  5. Go to File, then select Open, then select Browse and navigate to the location where you saved the downloaded flat file.

  6. Change the file extension type from ‘all excel files’ to ‘all files’.

  7. Select the flat file you downloaded, then select ‘open’.

  8. Use the Text Import Wizard to import the file as tab delimited data, Microsoft Excel should detect the file format, so you can select ‘next’ twice and then select finish.

In addition to the flat text files which have been available in the past, there are two new files which will now be available. These files (cu.aspect for CPI-U and cw.aspect for CPI-W) have columns as shown in Table 2 below.

Table 2: Example CPI aspect metadata
series_id year period aspect_type value footnote_codes

CUUR0000SA0

 2020 M08 I1 100

Where:

  • series_id is the CPI series ID code for the series to which the aspect data corresponds (the CPI-U NSA US city average series for all items CUUR0000SA0 in the example).

  • year is the year to which the aspect data corresponds (2020 in the example).

  • period is the month to which the aspect data corresponds with January being month 1, February month 2, and so on (month 8 – August – in the example).

  • aspect_type is the aspect type code (I1 – end of year relative importance – in the example).

  • value is the aspect datapoint itself (100 in the example).

  • footnote_codes will show and footnote codes, when applicable (none in the example).

Using the BLS public data API

An API (Application Programming Interface) is a tool that allows third party developers and organizations to access and manipulate data. The BLS Public Data API allows such users to access and manipulate published BLS survey data.

The BLS’ Public Data API gives the public access to economic data from all BLS programs. It is the Bureau's hope that talented developers and programmers will use the BLS Public Data API to create original, inventive applications with published BLS data.

More information is available on the BLS public data API page.

Last Modified Date: November 27, 2024