Get Started¶

In order to have your own sweet STAC FastAPI running, follow these steps.

Install¶

Our code is available on PyPI for easy install:

# Create a virtual environment
python -m venv env
source ./env/bin/activate

# Install core dependencies
python -m pip install stac-fastapi.types stac-fastapi.api stac-fastapi.extensions uvicorn

This gets you the main code, but then, you need a backend.

Backend¶

You can choose one between all availables.

For this tutorial, let's say you want to use the PgSTAC backend. First, we can install it:

python -m pip install stac-fastapi.pgstac

Then, you need a PostgreSQL database with PgSTAC enabled. You can either rely on a pre-installed database on your machine, or use a Docker image.

Local database Docker

# Download PgSTAC
git clone https://github.com/stac-utils/pgstac.git
cd pgstac/src/pgstac-migrate/

# Install dependencies
python -m venv env
source ./env/bin/activate
pip install -e .

# Add PgSTAC structures to database
# Note that your PostgreSQL user needs superuser permissions to do the install
pgstac-migrate migrate -d postgres://myuser@localhost:5432/database

# Give PgSTAC admin rights as well
psql -d postgres://myuser@localhost:5432/database -c "GRANT pgstac_admin TO myuser"

# Get PgSTAC FastAPI code
git clone https://github.com/stac-utils/stac-fastapi-pgstac.git
cd stac-fastapi-pgstac

# Start Docker database
make run-database

Running the API¶

In order to make API run, you need a little .env configuration file, let's create one:

PGUSER=myuser
PGPASSWORD=mypassword
PGHOST=localhost
PGPORT=5432
PGDATABASE=database

Note

If you're using the Docker database, make sure to also have these settings:

PGUSER=username
PGPASSWORD=password
PGDATABASE=postgis
PGHOST=localhost
PGPORT=5439

From there, you can start the API with this command:

uvicorn stac_fastapi.pgstac.app:app --host 0.0.0.0 --port 8080

Your API is now running on localhost:8080 !

Personalize settings¶

You can make the API a bit more yours by changing the description settings in .env file:

STAC_FASTAPI_VERSION (string) is the version number of your API instance (this is not the STAC version).
STAC_FASTAPI_TITLE (string) should be a self-explanatory title for your API.
STAC_FASTAPI_DESCRIPTION (string) should be a good description for your API. It can contain CommonMark.
STAC_FASTAPI_LANDING_ID (string) is a unique identifier for your Landing page.

Tip

These changes are highly recommended, many tools of the STAC ecosystem like STAC Browser rely on these for proper display.

Load data¶

Once you're all setup, you may want to actually offer some data. This depends on which backend you've choose to use.

For example, with PgSTAC, you can:

Use PyPgSTAC helper CLI
Or directly use pgstac functions in SQL

Let's load a demo collection and item, directly in SQL:

-- Single collection
INSERT INTO pgstac.collections (content)
SELECT jsonb_build_object(
    'type', 'Collection',
    'id', '1',
    'extent', jsonb_build_object(
        'temporal', jsonb_build_object(
            'interval', json_build_array(
                json_build_array(
                    '2026-01-01',
                    '2026-12-31'
                )
            )
        ),
        'spatial', jsonb_build_object(
            'bbox', json_build_array(
                json_build_array(-180.0, -90.0, 180.0, 90.0)
            )
        )
    )
);

-- Single item
INSERT INTO pgstac.items_staging_upsert(content)
SELECT jsonb_build_object(
    'type', 'Feature',
    'id', '1',
    'geometry', ST_Point(-1.7, 48.7, 4326),
    'collection', '1',
    'properties', json_build_object(),
    'assets', json_build_object(
        'hd', json_build_object(
            'href', 'https://path.to/some/image',
            'roles', json_build_array('data'),
            'type', 'image/jpeg'
        )
    )
);

Once done, you can refresh your API and see all available collections at:

localhost:8080/collections

What's next¶

Check out the Development & Contributing guide for advanced topics, or the Tips & Tricks guide for good to know stuff.