Getting Started

Build your first Spatial Pack from scratch. By the end of this guide you will have installed the CLI, created sample geodata, written a Pipeline YAML, and produced a complete pack with a manifest.

Prerequisites

Python 3.11+ with pip
Git (to clone the repository)
A terminal (any OS)

Install the CLI

Clone the repository and install spatialpack with all optional features:

git clone https://github.com/spatial-properties/spatial.properties.git
cd spatial.properties/cli
pip install -e ".[full]"

Verify the installation:

spatialpack --version

Expected output:

spatialpack, version 0.1.0

Create a project directory

Set up a working directory for your first pack:
Terminal window
```
mkdir my-first-pack
cd my-first-pack
mkdir data
```

Create sample data

Save the following GeoJSON as data/sites.geojson. It contains three polygons representing development sites in Perth, Australia:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "name": "Site Alpha", "area_ha": 12.5, "zoning": "industrial" },
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[115.86, -31.95], [115.87, -31.95], [115.87, -31.96], [115.86, -31.96], [115.86, -31.95]]]
      }
    },
    {
      "type": "Feature",
      "properties": { "name": "Site Beta", "area_ha": 8.3, "zoning": "commercial" },
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[115.88, -31.94], [115.89, -31.94], [115.89, -31.95], [115.88, -31.95], [115.88, -31.94]]]
      }
    },
    {
      "type": "Feature",
      "properties": { "name": "Site Gamma", "area_ha": 22.1, "zoning": "rural" },
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[115.84, -31.97], [115.86, -31.97], [115.86, -31.98], [115.84, -31.98], [115.84, -31.97]]]
      }
    }
  ]
}

This is synthetic data — small enough for instant processing, with realistic properties for a site selection scenario.

Write a Pipeline YAML

Create a file called pipeline.yaml in the project root. This Pipeline tells the CLI how to process your source data into a Spatial Pack:

# Pipeline metadata
pipeline:
  name: my-first-pack
  version: "1.0"

# Output pack definition
pack:
  id: "my-org:demo:sites:v1"
  version: "1.0.0"
  title: "My First Spatial Pack"
  theme: site-selection
  geography: demo
  license: CC-BY-4.0
  region:
    bbox: [115.83, -31.99, 115.90, -31.93]
    crs: "EPSG:4326"

# Named data inputs
sources:
  sites:
    path: "data/sites.geojson"
    license: CC-BY-4.0
    format: geojson

# Processing stages (executed in order)
stages:
  - name: convert_sites
    action: convert.shp          # Converts any vector format to GeoParquet
    input: sites                  # References the "sites" source above
    output: "layers/sites.parquet"
    options:
      crs: EPSG:4326
      bbox: ${pack.region.bbox}   # Clips data to the pack bounding box
    layer:
      id: sites
      title: "Development Sites"
      type: vector

The Pipeline has four sections. pipeline names the build. pack defines output metadata including the bounding box and license. sources maps a name to each input file. stages lists the processing steps — here, a single stage that converts GeoJSON to GeoParquet.

Build the pack

Run the build command from your project directory:
Terminal window
```
spatialpack pack build pipeline.yaml -o ./output
```
Expected output:
```
Pipeline: my-first-pack v1.0
Pack: my-org:demo:sites:v1 v1.0.0

[1/1] convert_sites .......... OK (0.3s)

Pack built successfully!
  Layers: 1
  Output: ./output
  Manifest: ./output/spatialpack.json
```
What just happened? The CLI read your Pipeline YAML, resolved the ${pack.region.bbox} variable, converted the GeoJSON source to GeoParquet format, clipped it to the bounding box, and generated a spatialpack.json manifest describing the pack contents.

Explore the output

Your completed Spatial Pack has the following structure:

Directoryoutput/
- spatialpack.json The manifest — source of truth for the pack
- Directorylayers/
  - sites.parquet Your GeoJSON data converted to GeoParquet

Open spatialpack.json to see the manifest. It contains the pack ID, version, license, bounding box, and a reference to each layer:

{
  "pack_id": "my-org:demo:sites:v1",
  "version": "1.0.0",
  "title": "My First Spatial Pack",
  "theme": "site-selection",
  "license": {
    "id": "CC-BY-4.0"
  },
  "bbox": [115.83, -31.99, 115.90, -31.93],
  "crs": "EPSG:4326",
  "layers": [
    {
      "id": "sites",
      "title": "Development Sites",
      "type": "vector",
      "parquet": "layers/sites.parquet"
    }
  ]
}

Next steps

You have a working Spatial Pack. Here is where to go from here:

Cookbook recipes — step-by-step walkthroughs for common workflows like shapefile conversion, CRS transformation, and publishing to CDN
What is a Spatial Pack — deeper understanding of pack structure, immutable versioning, and governance
Pipeline Architecture — how the Pipeline system resolves variables, executes stages, and produces deterministic builds
CLI Reference — all options for spatialpack pack build, pack info, pack init, and pack publish