Documentation > IPUMS API Program > Upgrading Versions

Upgrading to a Newer API Version

Upgrading to Version 2

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.

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