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: <a href="https://github.com/mkeller3/FastGeospatial" target="_blank">https://github.com/mkeller3/FastGeospatial</a>

---

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-