Documentation > Workflows & Code > Explore Metadata > NHGIS > Shapefile Metadata

IPUMS NHGIS Shapefile Metadata

An NHGIS shapefile is a geometry file for geographic information systems (GIS) in shapefile format. An in-depth introduction is availble on the NHGIS website.

Below we provide examples in curl showing how to work with our API to access metadata about NHGIS shapefiles.

If you are an R or Python user, please note that we also provide language-native client libraries to make it easier to work with the IPUMS API using those languages.

Get a List of All Shapefiles

This API call will return a list of all available shapefiles.

curl -X GET \
  "https://api.ipums.org/metadata/shapefiles?collection=nhgis&version=2" \
  -H "Authorization: $MY_KEY" | jq

# Results 

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

[SNIP]

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

Note that this is a paginated endpoint. The default page size is 500 items. As there are more than 500 items in this example, the links->nextPage field contains the URL to retrieve the next page of results.

Shapefile Attributes

name: The unique identifier of the time series table.
year: The survey year in which the file’s represented areas were used for tabulations, which may be different than the vintage of the represented areas. See .
geographicLevel: The geographic level of the shapefile.
extent: The geographic extent which is covered by the shapefile.
basis: The derivation source of the shapefile.
sequence: The order the shapefile in which appears in the metadata API.