API Reference Guide

The National Structure Inventory (NSI) Application Programming Interface (API) provides access to the NSI structures through query by polygon, bounding box, or by FIPS code. This allows a user to fetch structures in multiple formats, programmatically, to support a variety of workflows.

Use Cases

Some use cases are ideal for API access, and some use cases are not. For situations where the same structure inventory is leveraged multiple times, it is best to download the inventory, store it locally and use the local copy rather than repetitively calling the API.

Root URL

The root url of the NSI API is:

https://nsi.sec.usace.army.mil/nsiapi/

CODE

The location of the NSI API root is intended to be fairly stable, but the location has changed over the life of the API. Therefore, it is good practice for an application to leverage a configuration file or a forward link application to proxy the url to mitigate the risk.

Structures

The structures endpoint provides structure data to the user as a geojson feature collection (fc) or a feature stream (fs), the default is feature collection. The structure of a feature returned by the API can be seen in this geojson feature block. The type of return can be declared by the fmt directive (e.g. &fmt=fc)

Structure as GeoJson Feature

{
	"type": "Feature",
	"geometry": {
		"type": "Point",
		"coordinates": [-81.575387, 30.262174]
	},
	"properties": {
		"fd_id": 496985931,
		"bid": "862W7C6F+VR9-5-4-4-4",
		"occtype": "RES1-1SWB",
		"st_damcat": "RES",
		"cbfips": "120310159233002",
		"pop2amu65": 1,
		"pop2amo65": 0,
		"pop2pmu65": 1,
		"pop2pmo65": 0,
		"sqft": 2305,
		"num_story": 1,
		"ftprntid": "12031_200491",
		"ftprntsrc": "NGA",
		"students": 0,
		"found_ht": 2,
		"val_struct": 214530.016,
		"val_cont": 107265.008,
		"val_vehic": 27000,
		"source": "P",
		"med_yr_blt": 2004,
		"firmzone": null,
		"o65disable": 0.26,
		"u65disable": 0.05,
		"x": -81.57538743,
		"y": 30.262173845,
		"ground_elv": 5.772984504699707
	}
}

CODE

GET

The structures endpoint is a GET protocol and has options for by bounding box (bbox) or by FIPS code (fips).

Structures By Bounding Box

https://nsi.sec.usace.army.mil/nsiapi/structures?bbox=-81.58418,30.25165,-81.58161,30.26939,-81.55898,30.26939,-81.55281,30.24998,-81.58418,30.25165

CODE

Structures By FIPS

https://nsi.sec.usace.army.mil/nsiapi/structures?fips=15005

CODE

The FIPS option by feature stream (fs).

Structures as Feature Stream by FIPS

https://nsi.sec.usace.army.mil/nsiapi/structures?fips=15005&fmt=fs

CODE

The FIPS option by feature collection (fc)

Structures as Feature Collection by FIPS

https://nsi.sec.usace.army.mil/nsiapi/structures?fips=15005&fmt=fc

CODE

GET – Private Fields for USACE Users

USACE users may access private fields by appending /internal/ to their call.

Structures By FIPS

https://nsi.sec.usace.army.mil/internal/nsiapi/structures?bbox=-81.58418,30.25165,-81.58161,30.26939,-81.55898,30.26939,-81.55281,30.24998,-81.58418,30.25165

CODE

POST

For a more complex polygon the NSI API has two options, posting the geojson body directly, or by providing a shape zip file to define the complex geometry for return.

Example POST call

https://nsi.sec.usace.army.mil/nsiapi/structures?fmt=fc

CODE

The post call expects the body to be specified as "application/json", here is an example POST body.

{
	"type": "FeatureCollection",
	"features": [{
		"type": "Feature",
		"geometry": {
			"type": "Polygon",
			"coordinates": [
				[
					[-121.504025, 38.588017],
					[-121.507201, 38.596202],
					[-121.503081, 38.599623],
					[-121.494153, 38.601568],
					[-121.484624, 38.600428],
					[-121.478701, 38.597342],
					[-121.473292, 38.590835],
					[-121.504025, 38.588017]
				]
			]
		},
		"properties": {}
	}]
}

CODE

Stats

The stats endpoint provides access to a set of statistics based only on the bbox argument.

Stats by Bounding Box

https://nsi.sec.usace.army.mil/nsiapi/stats?bbox=-81.58418,30.25165,-81.58161,30.26939,-81.55898,30.26939,-81.55281,30.24998,-81.58418,30.25165

CODE

Example Output

{
	"num_structures": 2735,
	"yrbuilt_min": 0,
	"yrbuilt_max": 2019,
	"num_story_mean": 1.216819012797075,
	"resunits_sum": 4009,
	"empnum_sum": 4175,
	"students_sum": 0,
	"sqft_mean": 2692.137241194882,
	"sqft_sum": 7362995.354668002,
	"pop2amu65_sum": 6176,
	"pop2amo65_sum": 894,
	"pop2pmu65_sum": 5817,
	"pop2pmo65_sum": 1014,
	"val_struct_sum": 862186732.9225047,
	"val_cont_sum": 620067852.1085016,
	"val_vehic_sum": 144099000,
	"med_yr_blt_min": 1982,
	"med_yr_blt_max": 2004,
	"ground_elv_max": 17.24753189086914,
	"ground_elv_min": 2.3555846214294434
}

CODE