Historic Summary

Historic Summary Method

historic.get_summary(
    search_items, 
    location_type, 
    csv=False, 
    output_dir='/output'
)

Provides information for all events that impacted the location including event name, type or cause, date, and the level of impact - flood depth to the building footprint on the property, or count of properties for other location types.

This method returns an array of HistoricSummary product for the given IDs. Optionally creates a csv file.

(More information on the Historic Summary product can be found on the Historic Summary Page on the First Street Foundation API Data Dictionary)

Arguments:

• search_items: list/file of SearchItems, parcels to retrieve historic summary information for.
• location_type: string, one of {property, neighborhood, city, zcta, tract, county, cd, state}, for the search item type.
• csv: bool, whether to create a CSV for the retrieved data.
• output_dir: string, location to output the created CSV (if csv is True).

Example (Command Line):

Call historic.get_summary on a list of FSIDs

python -m firststreet -p historic.get_summary -s 511447411;511447412;511447413 -l property
python -m firststreet -p historic.get_summary -s 540225;7924;631054 -l neighborhood
python -m firststreet -p historic.get_summary -s 1982200;1935265;3958002 -l city
python -m firststreet -p historic.get_summary -s 50156;50158;43935 -l zcta
python -m firststreet -p historic.get_summary -s 19153004900;39061007100;39153531702 -l tract
python -m firststreet -p historic.get_summary -s 19163;19047;39027 -l county
python -m firststreet -p historic.get_summary -s 1901;3903;3915 -l cd
python -m firststreet -p historic.get_summary -s 19;39 -l state

Call historic.get_summary on a lat/lng or address

python -m firststreet -p historic.get_summary -s 37.16314,-76.55782;38.50303,-106.72863 -l state
python -m firststreet -p historic.get_summary -s "New York";"Ohio" -l state

Call historic.get_summary on a file of SearchItems

python -m firststreet -p historic.get_summary -s sample_property.txt -l property
python -m firststreet -p historic.get_summary -s sample_neighborhood.txt -l neighborhood
python -m firststreet -p historic.get_summary -s sample_city.txt -l city
python -m firststreet -p historic.get_summary -s sample_zcta.txt -l zcta
python -m firststreet -p historic.get_summary -s sample_tract.txt -l tract
python -m firststreet -p historic.get_summary -s sample_county.txt -l county
python -m firststreet -p historic.get_summary -s sample_cd.txt -l cd
python -m firststreet -p historic.get_summary -s sample_state.txt -l state

Example (Python File):

# Contents of sample.py
# Create a `FirstStreet` object.  
import firststreet
fs = firststreet.FirstStreet("api-key")

# Call historic.get_summary on a list of FSIDs
historic_summary = fs.historic.get_summary(search_items=[511447411, 511447412, 511447413], location_type="property", csv=True)
historic_summary = fs.historic.get_summary(search_items=[540225, 631054], location_type="neighborhood", csv=True)
historic_summary = fs.historic.get_summary(search_items=[1982200, 3958002], location_type="city", csv=True)
historic_summary = fs.historic.get_summary(search_items=[540225, 43935], location_type="zcta", csv=True)
historic_summary = fs.historic.get_summary(search_items=[19153004900, 39153531702], location_type="tract", csv=True)
historic_summary = fs.historic.get_summary(search_items=[19163, 39027], location_type="county", csv=True)
historic_summary = fs.historic.get_summary(search_items=[1901, 3915], location_type="cd", csv=True)
historic_summary = fs.historic.get_summary(search_items=[19, 39], location_type="state", csv=True)

# Call location.get_summary on a lat/lng or address
historic_summary = fs.historic.get_summary(search_items=[(37.16314,-76.55782)], location_type="county", csv=True)
historic_summary = fs.historic.get_summary(search_items=["New York, New York"], location_type="state", csv=True)

# Call historic.get_summary on a file of SearchItems
historic_summary = fs.historic.get_summary(search_items="sample_property.txt", location_type="property", csv=True)
historic_summary = fs.historic.get_summary(search_items="sample_neighborhood.txt", location_type="neighborhood", csv=True)
historic_summary = fs.historic.get_summary(search_items="sample_city.txt", location_type="city", csv=True)
historic_summary = fs.historic.get_summary(search_items="sample_zcta.txt", location_type="zcta", csv=True)
historic_summary = fs.historic.get_summary(search_items="sample_tract.txt", location_type="tract", csv=True)
historic_summary = fs.historic.get_summary(search_items="sample_county.txt", location_type="county", csv=True)
historic_summary = fs.historic.get_summary(search_items="sample_cd.txt", location_type="cd", csv=True)
historic_summary = fs.historic.get_summary(search_items="sample_state.txt", location_type="state", csv=True)

Historic Event Objects

Historic Summary Object

Key	Type	Description	Example
fsid	str	First Street ID (FSID) is a unique identifier assigned to each location.	392804911
valid_id	bool	Whether the input FSID returned valid data from the server.	True
historic	Array[dict]	The information associated with the event(s) as an array of dictionary for event(s) where the area of the model simulation of the historic event overlaps any area of the location. This includes event ID (unique First Street ID assigned to all modeled historic events), type, name and flood impact to the location. Impact includes the depth of flooding (in centimeters) to the building footprint for property searches or the total count of affected properties broken down by depth bin for other location types. Available depth bins begin at 5-10cm of flooding (displayed as "5") and are provided in 5 cm increments up to 120-125cm of flooding (displayed as "120"). Everything with greater than 125cm of flooding is bulked together at 125.	See below

Historic Summary (Property Location Type)

Key	Type	Description	Example
eventId	int	A unique First Street identifier assigned to each modeled historic event.	123
name	string	The name of the modeled historic event if it exists (note: several were strong pluvial events).	Hurricane Katrina
type	string	Categorization of event type (hurricane, fluvial, nor'easter, or tropical storm).	Hurricane
depth	int	The depth of flooding (in centimeters) to the building footprint for property searches. Flood depth is calculated at the lowest elevation of the building footprint (largest if more than 1 exists, or property centroid where footprint does not exist).	158

Historic Summary (Excluding Property Location Type)

Key	Type	Description	Example
eventId	int	A unique First Street identifier assigned to each modeled historic event.	123
name	string	The name of the modeled historic event if it exists (note: several were strong pluvial events).	Hurricane Katrina
type	string	Categorization of event type (hurricane, fluvial, nor'easter, or tropical storm).	Hurricane
data	Array[dict]	a collection of Historic Summary By Depth	See below

Historic Summary By Depth

Key	Type	Description	Example
bin	int	The depth of flooding (in centimeters ) from the historic event. Available depth bins begin at 5-10cm of flooding (displayed as "5") and are provided in 5 cm increments up to 120-125cm of flooding (displayed as "120"). Everything with greater than 125cm of flooding is bulked together at 125. Flood depth is calculated at the lowest elevation of the building footprint (largest if more than 1 exists, or property centroid where footprint does not exist).	20
count	int	The total count of affected properties for the specified depth bin for the location.	212