How to get access to characteristics from the CPS API

IPUMS API
1

Hello,
I am not able to find information on how to attach characteristics to a variables ? (for instance I tried to add SEX_SP as a variable in the list below without success)

extract = CpsExtract(
    ["cps1990_03s"],
    ["YEAR","SERIAL","MONTH","CPSID", "SEX"],
    description = "Test")
ipums.submit_extract(extract)

Any guideline would be greately appreciated
Paul

2

Hi Paul!

While the recently-released IPUMS API version 2 added support for attached characteristics, that support has not yet been added to the ipumspy client library, which currently supports IPUMS API version 1. The differences between what the API supports and what the client libraries support are indicated on this page (note the items with the asterisks): IPUMS API for IPUMS CPS | IPUMS Developer Portal

Currently, the only way to request attached characteristics via the API would be to make direct calls to the API by manually assembling your own JSON formatted request payloads and submitting them by making HTTP requests to the API. The reference documentation shows what a payload would look like with an attached characteristics example: Reference | IPUMS Developer Portal

I can’t offer a specific timeline for when ipumspy will support this, but the vast majority of our API users for our microdata collections interact with our API indirectly via the client libraries and it’s a high priority for us to bring the clients up to API v2 support. The team that develops the API is distinct from the teams that develop the client libraries, and while we try to coordinate our activity so that we can add support to the clients at the same time we add support to the API itself, this is not always possible. We realize this distinction is a bit blurry, and we intend to refactor our documentation site in the coming months to make this distinction more obvious.

3

Hello,
Thanks a lot for your answer !

4

Hi Paul, I wanted to provide a timing update for your question. I spoke with the ipumspy team and they are anticipating a new release with IPUMS API Version 2 support for the microdata collections within the next 2-4 weeks.

5

Hello
Thanks for this good news !

6

Hi Paul,

I’m happy to let you know that the attach characteristics feature is now supported in ipumspy! In your example extract from above, you can specify:

# define the extract
extract = CpsExtract(
    ["cps1990_03s"],
    ["YEAR","SERIAL","MONTH","CPSID", "SEX"],
    description = "Test")

# update SEX to attach spouse SEX value
extract.attach_characteristics("SEX", ["spouse"]

# submit the extract
ipums.submit_extract(extract)

Alternatively, you can use Variable objects to define variables and all of their features when you create your extract object as follows:

# define the extract
extract = CpsExtract(
    ["cps1990_03s"],
    [
    Variable(name="CPSID")
    Variable(name="SEX", attach_characteristics=["spouse"]
   ]
    description = "Test")

Note that YEAR, MONTH, and SERIAL are preselected by default and will be added to your extract even if you don’t specify them in your list of variables.

For more information on attaching characteristics and other extract features supported by the IPUMS API and ipumspy, see the Extract Features section of the ipumspy documentation.

Hope that helps!

1 Like
7

Hi Renae,
Thanks a lot for this update it works perfectly
Paul