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"
}

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
images		images
routers		routers
.gitignore		.gitignore
Dockerfile		Dockerfile
FastGeospatial.postman_collection.json		FastGeospatial.postman_collection.json
LICENSE		LICENSE
README.md		README.md
analysis_queries.py		analysis_queries.py
config.py		config.py
db.py		db.py
main.py		main.py
models.py		models.py
requirements.txt		requirements.txt
utilities.py		utilities.py

License

mkeller3/FastGeospatial

Folders and files

Latest commit

History

Repository files navigation

FastGeospatial

Requirements

Configuration

Usage

Running Locally

Production

API

Endpoint Description's

Analysis Status

Example Call

Example Output - Still Running

Example Output - Complete

Example Output - Error

Buffer

Description

Example Input

Example Output

Dissolve

Description

Example Input

Example Output

Dissolve By Value

Description

Example Input

Example Output

Square Grids

Description

Example Input

Example Output

Hexagon Grids

Description

Example Input

Example Output

Bounding Box

Description

Example Input

Example Output

K Means Cluster

Description

Example Input

Example Output

Center Of Each Polygon

Description

Example Input

Example Output

Center Of Dataset

Description

Example Input

Example Output

Find Within Distance

Description

Example Input

Example Output

Convex Hull

Description

Example Input

Example Output

Aggregate Points By Grid

Description

Example Input

Example Output

Aggregate Points By Polygons

Description

Example Input

Example Output

Select Inside

Description

Example Input

Example Output

Select Outside

Description

Example Input

Example Output

Clip