### Connect to portal with gratisgis client

Source: https://gratisgis.org/help/reference/scripts

Use the gratisgis client to connect to the portal. The client is installed and already pointed at this portal. from_env() works because the portal puts a key for this run in the environment, created when the run starts, carrying the permissions of whoever the run acts as, and revoked when the run ends.

```python
from gratisgis import GratisGIS

gg = GratisGIS.from_env()
print("running as", gg.whoami()["username"])

```

--------------------------------

### Install the Python client package

Source: https://gratisgis.org/help/reference/api-keys

Install the 'gratisgis' Python package to use the client in your scripts.

```bash
pip install gratisgis
```

--------------------------------

### Install gratisgis with pip

Source: https://gratisgis.org/help/reference/python-client

Install the `gratisgis` Python package. Requires Python 3.9 or newer and the `httpx` dependency.

```bash
pip install gratisgis

```

--------------------------------

### Start script runner and executor with Docker Compose

Source: https://gratisgis.org/help/reference/scripts

Use this Docker Compose command to start the script-runner and script-executor services with the scripts profile. This is part of enabling the scripting feature.

```bash
docker compose --profile scripts up -d script-runner script-executor

```

--------------------------------

### Scheduled Job Example

Source: https://gratisgis.org/help/reference/python-client

A complete example of a scheduled job that reads a layer, buffers geometries, and replaces the contents of a target layer.

```APIDOC
## Scheduled Job Example

### Description
A complete script that reads features from a source layer, buffers them, and writes the result to a target layer. Designed to be run as a scheduled job in a script item.

### Prerequisites
- `gratisgis` library installed.
- `shapely` and `pyproj` libraries installed.
- Environment variables configured for `GratisGIS.from_env()`.

### Code
```python
import sys
from gratisgis import GratisGIS, PortalError
from shapely.geometry import shape, mapping
from shapely.ops import transform
from pyproj import Transformer

SOURCE = "your-source-item-id"
TARGET = "your-target-item-id"

def main() -> int:
    gg = GratisGIS.from_env()
    to_m = Transformer.from_crs("EPSG:4326", "EPSG:32617", always_xy=True).transform
    to_deg = Transformer.from_crs("EPSG:32617", "EPSG:4326", always_xy=True).transform

    out = []
    for f in gg.iter_features(SOURCE, "parcels"):
        if not f.get("geometry"):
            continue
        ring = transform(to_deg, transform(to_m, shape(f["geometry"])).buffer(100))
        out.append({
            "type": "Feature",
            "geometry": mapping(ring),
            "properties": {"parcel_id": f["properties"].get("parcel_id")},
        })

    result = gg.add_features(TARGET, "buffered", out)
    print(f"wrote {result['inserted']} features")
    return 0

if __name__ == "__main__":
    try:
        sys.exit(main())
    except PortalError as err:
        print(f"failed: {err}", file=sys.stderr)
        sys.exit(1)
```

### Notes
- The script uses `iter_features` to stream features.
- `add_features` replaces the contents of the target layer.
- A non-zero exit code marks the run as failed in the portal's run history.
```

--------------------------------

### Token syntax example

Source: https://gratisgis.org/help/items/report-template

Placeholders in the document body use double curly braces. The example shows a field interpolation, a for loop over rows with a date filter, and a map placeholder. Filters like date, upper, round are documented on the Template tokens reference page.

```plaintext
{{ feature.field_name }}
{{ for row in inspections }}
  {{ row.inspected_at | date('Y-m-d') }}: {{ row.notes }}
{{ end }}
{{ map(layer='hydrants', bbox=feature.bbox, w=400, h=300) }}

```

--------------------------------

### GET /api/public/stac/search

Source: https://gratisgis.org/help/reference/api

Search STAC items using GET method.

```APIDOC
## GET /api/public/stac/search

### Description
Search STAC items using GET method.

### Method
GET

### Endpoint
/api/public/stac/search

### Parameters
#### Query Parameters
- **bbox** (string) - Optional - Bounding box filter.
- **limit** (integer) - Optional - Maximum number of items to return.
- **datetime** (string) - Optional - Datetime filter.

### Response
#### Success Response (200)
- Item collection (JSON) - STAC item collection.

#### Response Example
{
  "type": "FeatureCollection",
  "features": []
}

```

--------------------------------

### Connect to GratisGIS with API key

Source: https://gratisgis.org/help/reference/python-client

Create a `GratisGIS` client by passing the portal URL and an API key. The `whoami()` method returns the authenticated user's info. The API key is created at Profile → API keys.

```python
from gratisgis import GratisGIS

gg = GratisGIS("https://your-portal.example", api_key="ggk_...")
print(gg.whoami()["username"])

```

--------------------------------

### Connect using environment variables

Source: https://gratisgis.org/help/reference/python-client

Use `GratisGIS.from_env()` to read the `GRATISGIS_URL` and `GRATISGIS_API_KEY` environment variables. Inside a script item these variables are already set, so the same file runs on laptop and server.

```python
gg = GratisGIS.from_env()   # reads GRATISGIS_URL and GRATISGIS_API_KEY

```

--------------------------------

### Use API key with Python client

Source: https://gratisgis.org/help/reference/api-keys

Initialize the GratisGIS client with your API key and fetch features from a data layer. Replace 'ggk_...' with your actual key and 'your-portal.org' with your portal URL.

```python
from gratisgis import GratisGIS

gg = GratisGIS("https://your-portal.org", api_key="ggk_...")
layer = gg.find_items(type="data_layer", query="parcels")[0]
fc = gg.read_features(layer["id"], "parcels", limit=500)
```

--------------------------------

### GET /api/public/stac/collections

Source: https://gratisgis.org/help/reference/api

List of STAC collections available.

```APIDOC
## GET /api/public/stac/collections

### Description
List of STAC collections available.

### Method
GET

### Endpoint
/api/public/stac/collections

### Response
#### Success Response (200)
- Collections (JSON) - List of STAC collections.

#### Response Example
{
  "collections": []
}

```

--------------------------------

### GET /api/items/:id/layers/:layer/geojson

Source: https://gratisgis.org/help/reference/api

Exports the layer as GeoJSON.

```APIDOC
## GET /api/items/:id/layers/:layer/geojson

### Description
Exports the layer as GeoJSON.

### Method
GET

### Endpoint
/api/items/:id/layers/:layer/geojson

### Parameters
#### Path Parameters
- **id** (string) - Required - The item's ID.
- **layer** (string) - Required - The layer's ID.

### Response
#### Success Response (200)
- GeoJSON FeatureCollection.

#### Response Example
{
  "type": "FeatureCollection",
  "features": []
}
```

--------------------------------

### Enable scripts with environment variables

Source: https://gratisgis.org/help/reference/scripts

Set these environment variables to enable the scripting feature. Both are off by default. Replace the token with a long random string.

```bash
PORTAL_SCRIPTS_ENABLED=1
SCRIPT_EXECUTOR_TOKEN=<a long random string>

```

--------------------------------

### Create a derived layer with buffer and dissolve steps

Source: https://gratisgis.org/help/reference/python-client

Use this to create a derived layer on the server without downloading data. The pipeline runs on PostGIS when the layer is read, so the result is not a copy and follows later edits. `buffer()` uses `ST_Buffer` on the geography type, so 100 metres is 100 metres anywhere on Earth without choosing a projection. Available steps include `buffer`, `dissolve`, `centroid`, `convex-hull`, `bbox`, `simplify`, `vertices`, `densify`, `top-n`, `random-sample`, `nearest-neighbor`, `fishnet`, `calculate-geometry`, `filter`, `calculate-field`, `aggregate`, `spatial-join`, `spatial-filter`, `clip`, `erase`, `contour`; note `clip` and `erase` rather than `intersect` and `difference`. The result reads like any other layer, so `iter_features`, `export_layer` and the rest work on it unchanged.

```python
from gratisgis import buffer, step

# Look before you commit: runs the pipeline, returns a small sample,
# saves nothing.
preview = gg.preview_pipeline(item_id, "parcels", [buffer(100)])

derived = gg.create_derived_layer(
    "Parcels buffered 100m",
    item_id, "parcels",
    [buffer(100), step("dissolve", fields=["county"])],
)

```

--------------------------------

### GET /api/public/ogc

Source: https://gratisgis.org/help/reference/api

Landing document for the OGC API Features endpoint.

```APIDOC
## GET /api/public/ogc

### Description
Landing document for the OGC API Features endpoint, describing the service and its capabilities.

### Method
GET

### Endpoint
/api/public/ogc

### Response
#### Success Response (200)
- Landing document (JSON) - Self-describing document for the OGC API Features service.

#### Response Example
{
  "title": "OGC API Features",
  "links": []
}

```

--------------------------------

### GET /api/public/ogc/conformance

Source: https://gratisgis.org/help/reference/api

Conformance declaration for the OGC API Features endpoint.

```APIDOC
## GET /api/public/ogc/conformance

### Description
Conformance declaration for the OGC API Features endpoint, listing the conformance classes supported.

### Method
GET

### Endpoint
/api/public/ogc/conformance

### Response
#### Success Response (200)
- Conformance classes (JSON) - List of conformance classes supported.

#### Response Example
{
  "conformsTo": ["http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core", "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson", "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/crs"]
}

```

--------------------------------

### Send API key as bearer token with curl

Source: https://gratisgis.org/help/reference/api-keys

Use this curl command to authenticate with your API key. Replace 'ggk_your_key_here' with your actual key and 'your-portal.org' with your portal URL.

```bash
curl -H "Authorization: Bearer ggk_your_key_here" \
  https://your-portal.org/api/users/me
```