🧭 Geoflip

Geoflip is a FastAPI-based geospatial transformation engine. Designed for self-hosting and containerized deployment, it supports basic spatial operations like buffer and union over GeoJSON and Shapefile (SHP) inputs. Reprojection is handled automatically in each request.

Geoflip is built with developers in mind — stateless, simple to deploy, and built for automation.

---

✅ Features

• 🗂 Input formats: GeoJSON, Shapefile (SHP)
• 🔧 Currently Supported transformations:
  • buffer
  • union
• 🌐 Reprojection via transformation endpoint, and specifiying desired output format and crs
• ⚙️ Asynchronous job processing with Celery + Redis
• 🐳 Dockerized services for local deployment

---

📁 Folder Structure

/
├── server/         # FastAPI backend and transformation logic
├── deploy/         # Docker Compose and container configs
├── tests/          # Unit and integration tests
├── .env-example    # Sample environment variable file
└── README.md

---

🚀 Quick Start (Docker Compose)

Make sure you have docker desktop installed:

Windows Mac

then:

git clone https://github.com/geoflip-io/geoflip.git
cd geoflip/deploy

# Copy environment config - testing commit
cp .env-example .env

# Start API, Redis, and Worker (from the deploy folder)
cd /deploy

now in this folder create a .env with your config or just make a copy of the .env-example and rename it to .env

docker compose --profile infra --profile app up --build -d

Refer to /server.readme.md for additional local development details

🔁 Example Transform Requests

GeoJSON Input

POST /transform
Content-Type: multipart/form-data

Form fields:

• config: JSON config (see below)
• input_file: a .geojson file containing valid geojson as content

{
  "input": {
    "type": "geojson"
  },
  "transformations": [
    {
      "type": "buffer",
      "params": { "distance": 50, "units": "meters" }
    }
  ],
  "output": {
    "format": "shp", // shp, geojson, dxf is currently supported
    "epsg": 4326
  }
}

---

SHP Input

POST /transform
Content-Type: multipart/form-data

Form fields:

• config: JSON config (see below)
• input_file: zipped SHP (must include .shp, .shx, .dbf, and .prj)

{
  "input": {
    "type": "shp"
  },
  "transformations": [
    {
      "type": "buffer",
      "params": { "distance": 500, "units": "meters" }
    },
    {
      "type": "union"
    }
  ],
  "output": {
    "format": "shp", // shp, geojson, dxf is currently supported
    "epsg": 4326
  }
}

---

⏳ Async Job Flow

All transform jobs in Geoflip are asynchronous. You submit a job, then poll for its status and fetch the result when it's ready.

1. Submit Transform Request

• POST /transform
• Returns: { "job_id": "<uuid>" }

2. Check Job Status

GET /result/status/{job_id}

Example response:

{
  "status": "complete",
  "output_url": "/result/output/abc123"
}

3. Download Output

GET /result/output/{job_id}

This returns the data either directly (ie GeoJSON) or the transformed file (ie zipped SHP).

---

🔭 Roadmap

Planned features and improvements:

• 📁 Additional formats: KML, GeoPackage, EsriJSON
• ✂️ More operations and transformations: clip, erase, simplify, append, explode
• ☁️ tests

---

📄 License

This project is licensed under the Apache License 2.0.

• See LICENSE for the full text (including the patent grant).
• See NOTICE for attribution notices and third-party components.
• By contributing, you agree that your contributions are licensed under Apache-2.0.

Note: These terms apply to the open-source code. Use of the free, publicly hosted Geoflip service at geoflip.io is governed by its own Terms of Service and Privacy Policy.

Tip: add SPDX-License-Identifier: Apache-2.0 to file headers where practical.