Skip to main content

🚀 Getting Started with Geoflip

Welcome! This guide shows how to make your first API request against the public Geoflip API at:

https://api.geoflip.io

1. At a Glance​

Geoflip is a stateless, asynchronous geoprocessing API.
Every request follows the same pattern:

  1. Submit a multipart form to POST /transform → receive a job_id.
  2. Poll GET /result/status/{job_id} until status is SUCCESS (or FAILED).
  3. Download from the output_url in the status response.

2. Request–Response Flow​

1) Submit transform​

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

Form fields:

  • config — required, JSON string describing input, transformations, and output.
  • input_file — required, the data file.
    • For geojson: a .geojson file
    • For shp: a .zip containing .shp, .shx, .dbf, .prj
    • For dxf: a .dxf file (requires input.epsg in config)

Response:

{ "job_id": "abcd-ef01-2345-6789" }

2) Poll job status​

Endpoint: GET /result/status/{job_id}

Possible responses:

{ "job_id": "abcd-ef01-2345-6789", "status": "QUEUED" }
{ "job_id": "abcd-ef01-2345-6789", "status": "RUNNING" }
{
  "job_id": "abcd-ef01-2345-6789",
  "status": "SUCCESS",
  "output_url": "https://api.geoflip.io/result/output/abcd-ef01-2345-6789"
}
{ "job_id": "abcd-ef01-2345-6789", "status": "FAILED", "error": "Details about the failure..." }

3) Download result​

Use the output_url provided:

curl -O https://api.geoflip.io/result/output/abcd-ef01-2345-6789
  • When output.to_file = true (default): returns a file
    • geojson → .geojson file
    • shp → .zip archive
    • dxf → .dxf file
  • When output.to_file = false and format = geojson: returns inline JSON.

3. Example Request (GeoJSON → SHP)​

Submit a job​

curl -X POST https://api.geoflip.io/transform \
  -F 'config={
    "input":{"format":"geojson"},
    "transformations":[{"type":"buffer","params":{"distance":100,"units":"meters"}}],
    "output":{"format":"shp","epsg":4326}
  }' \
  -F "input_file=@/path/to/input.geojson;type=application/geo+json"

Response:

{ "job_id": "123e4567-e89b-12d3-a456-426614174000" }

Check job status​

curl https://api.geoflip.io/result/status/123e4567-e89b-12d3-a456-426614174000

Example (success):

{
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "SUCCESS",
  "output_url": "https://api.geoflip.io/result/output/123e4567-e89b-12d3-a456-426614174000"
}

Download the result​

curl -O https://api.geoflip.io/result/output/123e4567-e89b-12d3-a456-426614174000

This downloads the transformed output (a zipped Shapefile in this example).

4. Supported Formats​

Inputs​

  • geojson — .geojson file (always assumed EPSG:4326)
  • shp — .zip containing .shp, .shx, .dbf, .prj
  • dxf — .dxf file (requires input.epsg in config)

Outputs​

  • geojson — inline JSON (to_file=false) or file (to_file=true)
  • shp — zipped archive (.shp, .shx, .dbf, .prj)
  • dxf — DXF file (R2018), with entities grouped into layers

5. Next Steps​