Historic Summary

Historic Summary Method

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

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 EventIds, events to retrieve historic event 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 with 2 FSIDs
python -m firststreet -p historic.get_summary -i 190836953;193139123 -l property

# Call historic.get_summary on a file of SearchItems
python -m firststreet -p historic.get_summary -f sample.txt -l property

Example (Python File):

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

# Call historic.get_events_by_location on a list with 2 property FSIDs
historic_event = fs.historic.get_summary([19, 31], location_type="state", csv=True)

# Call historic.get_events_by_location on a file of SearchItems
historic_event = fs.historic.get_summary("sample.txt", csv=True)

Historic Event Objects

Historic Summary Object

Key	Type	Description	Example
fsid	int	First Street ID (FSID) is a unique identifier assigned to each location.	392804911
event	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