Iggy Gets (stream)Lit

All of us at Iggy are incredibly excited to announce the soft launch of our API geared towards making location information easily accessible to developers, data scientists, and anyone working with location-focused products. Our API exposes users to a wide variety of data from high resolution fire risk data to demographic data down to the Census Block Group. Our data can be queried using a variety of techniques from a simple latitude and longitude input to more complex user-defined geometries.

Getting started is easy. Simply head over to our signup page to get an account and start using your 50,000 free API calls. With your Iggy account, you’ll have access to more than 175 datasets and the Iggy data catalog will continue to grow rapidly over the coming months. Lindsay, CEO of Iggy, gives you more detail and lays out our motivation for building Iggy in her soft launch post here.

Retrieving Iggy data and displaying results in a web mapping application is a common pattern for many of our users. I have been a huge fan of streamlit for rapidly creating beautiful data-driven applications and I wanted to share a simple example for using the Iggy API with streamlit. Streamlit offers several ways to embed dynamic maps within an application, but I find that pydeck offers the most flexibility for presenting location data from a wide variety of geometry types. PyDeck is a Python-based library that provides access to deck.gl mapping utilities which allows users to create beautiful frontend mapping applications using a variety of geometries.

One of the datasets in the Iggy data catalog I am most excited about is the US Census American Community Survey (ACS) data. I’ve personally worked with ACS data for over a decade and found that its value continually proves itself across use cases, industries, and analytical contexts. The usefulness (and difficulty to work with) has been written about ad nauseum so I’ll direct the reader here, here, and here for some of my favorites. There have been some notable efforts over the years to make it easier to retrieve Census data including the tidycensus R package, US Census TIGERLine files, and more recently Safegraph’s Open Census Data. But what if you aren’t writing code in R (or don’t want to)? What if you don’t care about the differences between the North American Datum of 1983 (NAD83) and the World Geodetic System of 1984 (WGS84)? What if you simply want to retrieve the Census block group polygon associated with a latitude and longitude instead of downloading a bulk file? These are the types of issues we’ve set out to alleviate for developers when we built Iggy.

So what’s so cool about ACS data? Well do you know the median rent price in your census block group? Do you know the proportion of adults 65 years or older? Do you even know what census block group you live in? Iggy helps you answer these questions with a simple API call. We also take the pain out of conducting joins between geometries and attribute data. It’s all there in the response and there are thousands of attributes the US Census collects at the block group level (the lowest administrative unit the full ACS is conducted).

Let’s take a look at a quick example using Iggy’s API and the ACS housing block group dataset. We’ll use a small parcel dataset from the Thousand Oaks neighborhood in Alameda county California as the basis for our lookups. We can use the geometry of the parcel to Ask Iggy! what census block group it lies in and what the housing attributes are for that block group. Then we’ll display the parcel, block group boundary, and housing attributes in a simple streamlit lookup application.

First, let’s retrieve the block group and housing attributes from Iggy. I wrote a small function to do this so I can easily call the API on subsequent lookups via a dropdown list of addresses in streamlit. The function takes an input geometry (the parcel geojson polygon) and returns the Iggy response (including the block geometry) so we can use it in a map and table.

def get_cbgs(geometry):
url = "https://api.iggy.cloud/features/v1/datasets/" \
         "acs_census_blockgroup_housing/select/geojson"

    payload = geometry
    headers = {"Accept": "application/json",
               "Content-Type": "application/json",
               "X-Iggy-Token": Iggy_Key}

    response = requests.request("POST",
                                url,
                                json = payload,
                                headers = headers)
    return response

Let’s breakdown what’s happening here. We are using the Iggy Get Features for Geojson endpoint to retrieve the block group that intersects with our parcel boundary. You can see all of the ways we can query the dataset in the Iggy API reference here. In our case we use a POST method to provide the parcel boundary geojson and the Iggy response provides the census block group boundary as a geometry and the block group housing attributes as an object that we can parse in our app. Let’s see this in action:

Awesome. Now let’s take a look at how easy it is to build this functionality in streamlit. I’ve created another function that creates the pydeck map using the parcel boundary (red) and the block group boundary (dark blue).

def create_map(cbg, parcel, lat, lon, zoom):
    map = pdk.Deck(
        map_provider="mapbox",
        map_style="mapbox://styles/mapbox/light-v9",
        initial_view_state={
            "latitude": lat,
            "longitude": lon,
            "zoom": zoom
        },
        layers=[
            pdk.Layer(
                "GeoJsonLayer",
                data=cbg,
                get_position=["lon", "lat"],
                radius=100,
                pickable=False,
                getFillColor=[3, 17, 86, 255],
                opacity=0.5
            ),
            pdk.Layer(
                "GeoJsonLayer",
                data=parcel,
                get_position=["lon", "lat"],
                pickable=False,
                stroked=True,
                filled=True,
                getLineColor=[218, 41, 28, 255],
                getFillColor=[218, 41, 28, 255]
            ),
        ],
    )
    return map

The function takes the block group geojson, parcel geojson, latitude, longitude, and a zoom level and returns a pydeck map that we can use in streamlit to update the map display. We use the GeoJsonLayer pydeck layer to create our map layers and set some properties to get the look and feel we want. To display this map in streamlit we simply call the function with the appropriate input and use the streamlit pydeck_chart method to add it to our app.

deck_map = create_map(
    iggy_cbgs_gdf,
    parcel_sel_gdf,
    parcel_sel_gdf.centroid.y.iloc[0],
    parcel_sel_gdf.centroid.x.iloc[0],
    14,
)
st.pydeck_chart(deck_map)

Now let’s wrap this up by displaying the block group housing attributes in a table. We can use the properties from the Iggy response to parse out the housing attributes and add it to our app by using the streamlit dataframe method. In this case I created a new pandas series and dataframe from the properties object and pass it to streamlit.

props_s = pd.Series(iggy_cbgs_df["properties"].iloc[0])
props_df = props_s.to_frame().rename(columns={0: "Value"})
st.dataframe(props_df)

Let’s take a final look at the app with the housing attributes added as a table:

Awesome! Using Iggy and streamlit we were able to quickly retrieve a rich set of housing attributes and block group boundaries with just a few lines of code. You can see the full code example and browse some other sample code here. We can’t wait to see what you do with Iggy. Head over to the signup page and get started. If you have any questions reach out to us on our Discord community or if you have any suggestions for functionality or datasets you want to see in our catalog submit a request here.