API Versions

Documentation > IPUMS API Program > Upgrading Versions

Upgrading to a Newer API Version

NOTE: These instructions are for those who have code which interacts with the IPUMS API directly via RESTful HTTP calls. If you use ipumspy or ipumsr to interact with the IPUMS API, you will first need to wait for those SDKs to add support for IPUMS API Version 2, and then follow their upgrade instructions.

Upgrading to Version 2, May 2024 Update

  • The May 2024 Update did not introduce any breaking changes so existing code should continue to function, but to take advantage of the new data collections and features that were introduced in the update you will need to utilize additional attributes in the data request payload. See the OpenAPI reference documentation for all of the new schema elements.

  • Non-breaking changes don’t require a version increment, so you should continue to use version=2 for the API version parameter.

  • If your code is consuming NHGIS metadata endpoints you are advised to adopt the new endpoint URL style (/metadata/data_tables?collection=nhgis) as the old style (/metadata/nhgis/data_tables) may be deprecated in a future version.

Upgrading to Version 2

To upgrade your code to IPUMS API Version 2, make the following changes to your code:

  • Change all JSON payload constructing and parsing logic to use camelCase member keys instead of snake_case.

    In this example, data_structure has changed to dataStructure and data_format has changed to dataFormat.

    { "description": "Example hierarchical extract", "dataStructure": { "hierarchical": {} }, "dataFormat": "fixed_width", "samples": { "us2018a": {}, "us2019a": {} }, "variables":{ "AGE": {}, "SEX": {}, "RACE": {}, "STATEFIP": {} } }

  • Alter any code which parses the DataExtractResponse to navigate the new top-level member key extractDefinition.

    In this example, fields including description, samples, variables and dataFormat were formerly at the top level. Now they are nested within extractDefinition.

      {
      "number": 1,
      "status": "completed",
      "downloadLinks": {
          "basicCodebook": {
              "url": "https://api.ipums.org/downloads/cps/api/v1/extracts/1234567/cps_00001.cbk",
              "bytes": 8492,
              "sha256": "37ce64df8300c73736e7fcfd6c4afb9faaddceddfe3a73bcaa435984ce3c2765"
          },
          "stataCommandFile": {
              "url": "https://api.ipums.org/downloads/cps/api/v1/extracts/1234567/cps_00001.do",
              "bytes": 11741,
              "sha256": "fbad44930e54c3889a3e2e1eb3d04c48ed34743ceb70fcdda66168183ff1670b"
          },
          "data": {
              "url": "https://api.ipums.org/downloads/cps/api/v1/extracts/1234567/cps_00001.dat.gz",
              "bytes": 4577233,
              "sha256": "68851b34fa1841a145403b033786f1bb125fbbc8f85297f776075df187e3a41f"
          },
          "rCommandFile": {
              "url": "https://api.ipums.org/downloads/cps/api/v1/extracts/1234567/cps_00001.R",
              "bytes": 406,
              "sha256": "3009d74bdadd0fadab6b18e9deafc7833a8ef6e8117e8ab3b68008f2f7c64296"
          },
          "spssCommandFile": {
              "url": "https://api.ipums.org/downloads/cps/api/v1/extracts/1234567/cps_00001.sps",
              "bytes": 5945,
              "sha256": "a29ff3ebc41a9bdc3ac65b71ceeef8179b12135607950aeee93ca362f7aa68b7"
          },
          "ddiCodebook": {
              "url": "https://api.ipums.org/downloads/cps/api/v1/extracts/1234567/cps_00001.xml",
              "bytes": 44616,
              "sha256": "fea25a5b6af215142fa55cf3fd9ec2784532643021ebecac4d56e0d17ba1e935"
          },
          "sasCommandFile": {
              "url": "https://api.ipums.org/downloads/cps/api/v1/extracts/1234567/cps_00001.sas",
              "bytes": 5990,
              "sha256": "45f571f15fb17d9dd326db094e26f9ecc335b87629b00d4813cbb47fdc855a64"
          }
      },
      "extractDefinition": {
          "version": 2,
          "dataStructure": {
              "rectangular": {
                  "on": "P"
              }
          },
          "dataFormat": "fixed_width",
          "caseSelectWho": "individuals",
          "description": "Example extract",
          "samples": {
              "cps2018_03s": {},
              "cps2019_03s": {}
          },
          "variables": {
              "YEAR": {
                  "preselected": true
              },
              "SERIAL": {
                  "preselected": true
              },
              "MONTH": {
                  "preselected": true
              },
              "CPSID": {
                  "preselected": true
              },
              "ASECFLAG": {
                  "preselected": true
              },
              "ASECWTH": {
                  "preselected": true
              },
              "STATEFIP": {},
              "PERNUM": {
                  "preselected": true
              },
              "CPSIDP": {
                  "preselected": true
              },
              "CPSIDV": {
                  "preselected": true
              },
              "ASECWT": {
                  "preselected": true
              },
              "AGE": {},
              "SEX": {},
              "RACE": {}
          },
          "collection": "cps"
      }
  }

  • Endpoints returning lists now feature pagination. This has changed the response structure.

    In this example, the response from the NHGIS shapefiles endpoint is now paginated. This endpoint returns a list in Version 1. In Version 2 it returns an object, and the list of shapefiles is now the value of the key data. This change makes room for the pagination information stored in the keys links, pageNumber, pageSize, and totalCount. The URLs for the next and previous pages are found in the nextPage and previousPage child keys within links, and will be None when at one of the list boundaries.

      # Call is to https://api.ipums.org/metadata/nhgis/shapefiles?version=2

  # Results

  { 'data': [ { 'basis': '2000 TIGER/Line +',
              'extent': 'United States',
              'geographicLevel': 'State',
              'name': 'us_state_1790_tl2000',
              'sequence': 1,
              'year': '1790'},
              { 'basis': '2000 TIGER/Line +',
              'extent': 'United States',
              'geographicLevel': 'County',
              'name': 'us_county_1790_tl2000',
              'sequence': 2,
              'year': '1790'},
              { 'basis': '2008 TIGER/Line +',
              'extent': 'United States',
              'geographicLevel': 'County',
              'name': 'us_county_1790_tl2008',
              'sequence': 3,
              'year': '1790'},

  [SNIP]

              { 'basis': '2010 TIGER/Line +',
              'extent': 'Nebraska',
              'geographicLevel': 'Block',
              'name': '310_block_2000_tl2010',
              'sequence': 498,
              'year': '2000'},
              { 'basis': '2010 TIGER/Line +',
              'extent': 'Nevada',
              'geographicLevel': 'Block',
              'name': '320_block_2000_tl2010',
              'sequence': 499,
              'year': '2000'},
              { 'basis': '2010 TIGER/Line +',
              'extent': 'New Hampshire',
              'geographicLevel': 'Block',
              'name': '330_block_2000_tl2010',
              'sequence': 500,
              'year': '2000'}],
  'links': {  'nextPage': 'https://api.ipums.org/metadata/nhgis/shapefiles?pageNumber=2&pageSize=500&version=2',
              'previousPage': None},
  'pageNumber': 1,
  'pageSize': 500,
  'totalCount': 1858}

  • Change all version query parameters to version=2

    https://api.ipums.org/extracts/?collection=nhgis&version=v1 becomes https://api.ipums.org/extracts/?collection=nhgis&version=2