FastGeospatial

FastGeospatial is a PostGIS geospatial api to enable geospatial analyses on geographical data within a spatial database. FastGeospatial is written in Python using the FastAPI web framework.

Source Code: https://github.com/mkeller3/FastGeospatial

Requirements

FastGeospatial requires PostGIS >= 2.4.0.

Configuration

In order for the api to work you will need to edit the config.py file with your database connections.

Example

DATABASES = {
    "data": {
        "host": "localhost",
        "database": "data",
        "username": "postgres",
        "password": "postgres",
        "port": 5432,
    }
}

Usage

Running Locally

To run the app locally uvicorn main:app --reload

Production

Build Dockerfile into a docker image to deploy to the cloud.

API

Method	URL	Description
`GET`	`/api/v1/analysis/status/{process_id}`	Analysis Status
`POST`	`/api/v1/analysis/buffer`	Buffer
`POST`	`/api/v1/analysis/dissolve`	Dissolve
`POST`	`/api/v1/analysis/dissolve_by_value`	Dissolve By Value
`POST`	`/api/v1/analysis/square_grids`	Square Grids
`POST`	`/api/v1/analysis/hexagon_grids`	Hexagon Grids
`POST`	`/api/v1/analysis/bounding_box`	Bounding Box
`POST`	`/api/v1/analysis/k_means_cluster`	K Means Cluster
`POST`	`/api/v1/analysis/center_of_each_polygon`	Center Of Each Polygon
`POST`	`/api/v1/analysis/center_of_dataset`	Center Of Dataset
`POST`	`/api/v1/analysis/find_within_distance`	Find Within Distance
`POST`	`/api/v1/analysis/convex_hull`	Convex Hull
`POST`	`/api/v1/analysis/aggregate_points_by_grids`	Aggregate Points By Grid
`POST`	`/api/v1/analysis/aggregate_points_by_polygons`	Aggregate Points By Polygons
`POST`	`/api/v1/analysis/select_inside`	Select Inside
`POST`	`/api/v1/analysis/select_outside`	Select Outside
`POST`	`/api/v1/analysis/clip`	Clip

Endpoint Description's

Analysis Status

Any time an analysis is submitted it given a process_id to have the analysis run in the background using FastAPI's Background Tasks. To check the status of an analysis, you can call this endpoint with the process_id.

Example Call

/api/v1/analysis/status/472e29dc-91a8-41d3-b05f-cee34006e3f7

Example Output - Still Running

{
    "status": "PENDING"
}

Example Output - Complete

{
    "status": "SUCCESS",
    "new_table_id": "shnxppipxrppsdkozuroilkubktfodibtqorhucjvxlcdrqyhh",
    "completion_time": "2022-07-06T19:33:17.950059",
    "run_time_in_seconds": 1.78599
}

Example Output - Error

{
    "status": "FAILURE",
    "error": "ERROR HERE",
    "completion_time": "2022-07-08T13:39:47.961389",
    "run_time_in_seconds": 0.040892
}

Buffer

Description

Buffer an geometric table with a buffer in kilometers.

Example: Buffer zip centroids by one kilometer.

Example Input

{
    "table": "zip_centroids",
    "database": "data",
    "distance_in_kilometers": 1
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Dissolve

Description

Dissolve any geometric table into one single geometry.

Example: Dissolve all the US States into one single geometry.

Example Input

{
    "table": "states",
    "database": "data"
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Dissolve By Value

Description

Dissolve any geometric table into geometries based off a column in the table.

Example: Dissolve US States based off a column in the table called sub_region.

Example Input

{
    "table": "states",
    "database": "data",
    "column": "sub_region"
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Square Grids

Description

Generate square grids of any size based off of a tables geometry.

Example: Generate 100 kilometers square grids based off of a table containing US States.

Example Input

{
    "table": "states",
    "database": "data",
    "grid_size_in_kilometers": "100"
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Hexagon Grids

Description

Generate hexagon grids of any size based off of a tables geometry.

Example: Generate 100 kilometers hexagon grids based off of a table containing US States.

Example Input

{
    "table": "states",
    "database": "data",
    "grid_size_in_kilometers": 100
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Bounding Box

Description

Generate a bounding box of a table.

Example: Find the bounding box of a table that contains all of the US States.

Example Input

{
    "table": "states",
    "database": "data",
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

K Means Cluster

Example: Group all US zip centroids into 5 groups based off of k means clusters.

Description

Use K Means Clustering to group points based on their location.

Example Input

{
    "table": "zip_centroids",
    "database": "data",
    "number_of_clusters": 5
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Center Of Each Polygon

Description

Find the center of each polygon for a given table.

Example: Find the center of each US State.

Example Input

{
    "table": "states",
    "database": "data"
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Center Of Dataset

Description

Find the center of all geometries based off a given table.

Example: Find the geomeric center of a table that contains all of the US States.

Example Input

{
    "table": "states",
    "database": "data"
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Find Within Distance

Description

Find all geometries within a given distance from a given point.

Example: Find all states within 500 kilometers of latitude 40.45 and latitude -88.95.

Example Input

{
    "table": "states",
    "database": "data",
    "latitude": 40.45,
    "longitude": -88.95,
    "distance_in_kilometers": 500
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Convex Hull

Description

Find the smallest convex hull around a given table.

Example: Find the smallest convex hull around all the US States.

Example Input

{
    "table": "states",
    "database": "data"
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Aggregate Points By Grid

Description

Aggregate a table of points into grids and determine how points are in each grid.

Example: Determine how many zip centroids are each 1000 kilometer hexagon grid.

Example Input

{
    "table": "zip_centroids",
    "database": "data",
    "distance_in_kilometers": 1000,
    "grid_type": "hexagon"
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Aggregate Points By Polygons

Description

Aggregate a table of points into a table of polygons and determine how points are in each polygon.

Example: Determine how many zip centroids are within each US State.

Example Input

{
    "table": "zip_centroids",
    "database": "data",
    "polygons": "states"
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Select Inside

Description

Find all geometries within a given polygon table.

Example: Find all zip centroids within the US States table.

Example Input

{
    "table": "zip_centroids",
    "database": "data",
    "polygons": "states"
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Select Outside

Description

Find all geomtries outside a given polygon table.

Example: Find all the zip centroids outside of the table with US States.

Example Input

{
    "table": "zip_centroids",
    "database": "data",
    "polygons": "states"
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}

Clip

Description

Clip any geometric table based of a polygon table.

Example: Clip the US States table to a large polygon.

Example Input

{
    "table": "states",
    "database": "data",
    "polygons": "big_polygon"
}

Example Output

{
  "process_id": "c8d7b8d8-3e82-4f93-b441-55a5f51c4171",
  "url": "http://127.0.0.1:8000/api/v1/analysis/status/c8d7b8d8-3e82-4f93-b441-55a5f51c4171"
}