geojibe

Official Python SDK and CLI for the GeoJibe geospatial processing platform and API.

geojibe is an HTTPS client for an existing GeoJibe installation. Processing stays on the server. It does not require Docker, GDAL, DuckDB, QGIS, Go, or a local GeoJibe server.

Fuller product documentation: GeoJibe Guides, including the command-line client.

Install

This package is published as geojibe:

pip install geojibe

or

pipx install geojibe

From a source checkout, Python 3.10 or newer:

cd clients/python
python -m pip install -e .

That provides the geojibe executable and the geojibe Python package.

Authenticate

Create a Personal Access Token in GeoJibe → Account → API Tokens, then:

geojibe auth login

Enter the GeoJibe URL (your installation origin, for example https://geojibe.example.com — not an /api/v1 path) and the token. Token input is hidden. On success: Authenticated successfully.

Use

geojibe jobs list
geojibe sources list
geojibe destinations list
geojibe recipes list
geojibe jobs run <id>
geojibe workspace upload roads.gpkg
geojibe transformations list

--json writes machine-readable JSON to stdout:

geojibe jobs list --json
ID=$(geojibe workspace upload roads.gpkg --json | jq -r '.id')

Automation

export GEOJIBE_URL=https://geojibe.example.com
export GEOJIBE_TOKEN=gjp_...

geojibe jobs list --json

Do not hard-code a hosted GeoJibe URL. Shared, Dedicated, and On-Site installations each have their own origin.

Credential precedence, highest wins:

1. --url / --token
2. GEOJIBE_URL / GEOJIBE_TOKEN
3. Saved configuration

Configuration

geojibe config set-url and geojibe config set-token write a user-level file, never the current working directory:

OS	Path
Linux	~/.config/geojibe/config.toml ($XDG_CONFIG_HOME if set)
macOS	~/Library/Application Support/geojibe/config.toml
Windows	%APPDATA%\geojibe\config.toml

That file may contain a Personal Access Token. Permissions are set to 0600 on Unix. geojibe config show prints a masked token only.

Logout removes the local token. It does not revoke the PAT. Revoke tokens in Account → API Tokens.

geojibe auth status
geojibe auth logout

Commands

geojibe --help
geojibe --version

geojibe auth …
geojibe config …
geojibe sources list|get|create|delete
geojibe destinations list|get|create|delete
geojibe jobs list|get|run|enable|disable|delete|create|update|runs|retry
geojibe recipes list|get|create|delete
geojibe workspace upload|info|preview|convert|download
geojibe workspace transform get|set|clear|preview
geojibe transformations list|show

Workspace processing is remote. Discover operations with geojibe transformations list and geojibe transformations show <id>.

geojibe workspace transform set <id> --file pipeline.json

{
  "layers": ["apiary"],
  "operations": [
    {"type": "buffer", "distance": 10, "units": "source"}
  ]
}

--debug prints HTTP method, URL, and status to stderr (never the token). --insecure disables TLS verification for development certificates only and is not saved. TLS verification is on by default.

geojibe jobs create --file job.json sends the public API body (POST /api/v1/jobs). Existing Job JSON without pipeline is unchanged and keeps legacy/inferred stage presence.

Optional Canvas stage flags:

{
  "name": "Neighborhoods",
  "source_id": "…",
  "transform_mode": "sql",
  "sql": "SELECT * FROM source WHERE population > 1000",
  "output_format": "GeoJSON",
  "destination_id": "…",
  "destination_target": {"schema": "public", "table": "neighborhoods", "write_mode": "replace"},
  "schedule": {"kind": "daily", "timezone": "UTC", "hour": 2, "minute": 0},
  "pipeline": {
    "transform": false,
    "convert": false,
    "python": false
  }
}

pipeline	Meaning
omitted	Legacy/inferred behavior (stages stay present)
{}	Legacy/inferred behavior (stages stay present)
explicit false	That stage is absent
explicit true	That stage is present

Create and update preserve explicit false flags. geojibe jobs get shows recorded stages when the Job includes pipeline.

Python

from geojibe import GeoJibe, ValidationError

client = GeoJibe(
    url="https://geojibe.example.com",
    token="gjp_...",
)

url and token may also come from GEOJIBE_URL and GEOJIBE_TOKEN when omitted. Explicit constructor arguments always win. The token is sent as Authorization: Bearer and is never logged, stored, or included in exceptions.

client.me()

Upload

ws = client.workspaces.upload("roads.gpkg")
print(ws.id, ws.status, ws.layers)

Preview

rows = ws.preview_data("roads", limit=50)
geojson = ws.preview_map("roads")["geojson"]

preview_data and preview_map return the server JSON, including fields, counts, truncation, and CRS. preview_map()["geojson"] is a GeoJSON FeatureCollection. Visualization is up to the caller.

Transform

Discover operations from the server (do not hard-code a catalog):

ops = client.transformations.list()

ws.set_transformations(
    layers=["roads"],
    operations=[{"type": "buffer", "distance": 10, "units": "source"}],
)

SQL and Python are sibling fields, not operation types:

ws.set_transformations(layers=["roads"], sql="SELECT * FROM source")
ws.set_transformations(python={"script": script, "filename": "script.py"})
ws.clear_transformations()

Transformed preview

Uses the stored pipeline. The SDK does not resend or execute it locally.

ws.preview_transformed_data("roads", limit=50)
ws.preview_transformed_map("roads")

Convert and download

ws.convert(output_format="GeoJSON", layers=["roads"])
output = ws.download("roads.geojson")

Download streams to disk. An existing file is not overwritten unless you pass overwrite=True. Convert is currently synchronous (status=completed).

Saved Sources, Destinations, Recipes, and Jobs keep their existing methods. Job create/update accept the same public body, including optional pipeline flags. Helpers inspect recorded stages without inventing missing keys:

from geojibe import (
    GeoJibe,
    PipelineStages,
    job_pipeline,
    job_write_body,
    pipeline_stages,
    stage_included,
)

jobs = client.jobs.list()
client.jobs.run(jobs[0]["id"])

created = client.jobs.create({
    "name": "Neighborhoods",
    "source_id": "...",
    "output_format": "GeoJSON",
    "pipeline": pipeline_stages(transform=True, convert=True, python=False),
})
job_pipeline(created)
stage_included(created, "python")

Omitting pipeline, or sending pipeline: {}, keeps /api/v1 legacy/inferred behavior. Explicit false removes that stage; leftover operations, format, or Python on the body do not restore it.

Errors

try:
    ws.preview_transformed_map("other_layer")
except ValidationError as exc:
    print(exc.status_code, exc.code, exc.message, exc.details)

timeout (default 30s) is the ordinary HTTP timeout. run_timeout (default 600s) is used for upload, preview, convert, and download.

Exit codes

Code	Meaning
0	Success
1	Failure (including a finished Run with status failed)
2	Usage / local config
3	Authentication (401 / missing credentials)
4	Authorization (403 / missing PAT scope)
5	Not found (404)
6	Validation (400 / 409 / 422)
7	Network (DNS, connection refused, TLS, timeout)
8	GeoJibe server error (5xx)

Security

• PAT is sent as Authorization: Bearer, never as a query parameter
• Full PAT is not printed by config show, auth status, or default errors
• Source and Destination secrets from the API are not displayed