Skip to main content

Overture + Fused

In these examples, we'll see ways to load and transform Overture data using Fused. The Fused Python library allows you to call predefined UDFs to load and process data into your Python environment.

Examples​

Join Overture Buildings and NSI​

This example shows how to join the Overture Buildings dataset with the National Structures Inventory (NSI) dataset. The NSI API provides point data on buildings in the U.S. that are relevant to hazard analyses. Joining the NSI data with Overture Buildings can be used to enrich Overture Building features with additional metadata.

We'll be loading Overture Buildings data using the Fused User Defined Function explained in this section of the docs.

First we import Fused.

import fused

Now we can define a GeoDataFrame with a bounding box of our area of interest. We'll use it to load data for the same area of each dataset.

import fused
import geopandas as gpd
import shapely

bbox = gpd.GeoDataFrame(
    geometry=[shapely.box(-73.9847, 40.7666, -73.9810, 40.7694)], 
    crs=4326
)

We use fused.run to run the predefined Overture UDF that loads Overture Buildings data for the given bbox area. We may specify the Overture theme with the overture_type parameter, and a subset of columns to fetch with the use_columns parameter.

gdf_overture = fused.run(
    "UDF_Overture_Maps_Example", 
    bbox=bbox, 
    overture_type='building', 
    use_columns=['geometry', 'names', 'sources']
)

To get the NSI data, we call the NSI API, defining the area using a GeoJSON derived from the bbox GeoDataFrame. After receiving the response, we convert it into a GeoDataFrame.

import requests
import json

# Convert to GeoJSON
bbox_geojson = json.loads(bbox.to_json())

# Make a request to the NSI API
response = requests.post(
    url="https://nsi.sec.usace.army.mil/nsiapi/structures?fmt=fc",
    json=bbox_geojson,
)

# Create a GeoDataFrame from the response
gdf_nsi = gpd.GeoDataFrame.from_features(response.json()["features"])

Now we can join the Overture and NSI data using a spatial join.

gdf_overture.sjoin(gdf_nsi, how='inner', predicate='intersects')

Create a Fused User Defined Function (UDF)​

We can encapsulate the above code into a UDF that can be referenced and reused in other workflows.

In this code, the @fused.udf decorator indicates that the function is a UDF. The function defines the area of interest using the bbox parameter. Note how the UDF imports are included in the function body.

import fused

@fused.udf
def udf(bbox):
    import json
    import geopandas as gpd
    import requests

    # 1. Load Overture Buildings
    gdf_overture = fused.run("UDF_Overture_Maps_Example", bbox=bbox, overture_type='building')

    # 2. Load NSI from API
    bbox_geojson = json.loads(bbox.to_json())
    response = requests.post(
        url="https://nsi.sec.usace.army.mil/nsiapi/structures?fmt=fc",
        json=bbox_geojson,
    )

    # 3. Create NSI gdf
    gdf_nsi = gpd.GeoDataFrame.from_features(response.json()["features"])

    # 4. Join Overture and NSI
    return gdf_overture.sjoin(gdf_nsi, how='inner', predicate='intersects')

Now we can run the UDF for an area specified by the bounding box.

fused.run(udf, bbox=bbox)

By encapsulating the code into a UDF, a workflow or client application can dynamically pass different areas of interest to the bbox parameter to run the UDF and return its output table. A simple way to try this is to run a UDF equivalent to the one we just created in the Fused UDF Builder which renders the UDF outputs on a map.

Next steps​

Last updated on