{"id":28956911,"url":"https://github.com/developmentseed/sat-api-pg","last_synced_at":"2025-06-23T21:41:12.528Z","repository":{"id":40604467,"uuid":"200575544","full_name":"developmentseed/sat-api-pg","owner":"developmentseed","description":"A Postgres backed STAC API.","archived":false,"fork":false,"pushed_at":"2022-12-22T12:59:55.000Z","size":865,"stargazers_count":30,"open_issues_count":26,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-25T00:27:05.762Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PLpgSQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/developmentseed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-05T03:26:31.000Z","updated_at":"2023-05-17T01:42:00.000Z","dependencies_parsed_at":"2023-01-30T09:30:37.626Z","dependency_job_id":null,"html_url":"https://github.com/developmentseed/sat-api-pg","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/developmentseed/sat-api-pg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fsat-api-pg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fsat-api-pg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fsat-api-pg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fsat-api-pg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/developmentseed","download_url":"https://codeload.github.com/developmentseed/sat-api-pg/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fsat-api-pg/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261561248,"owners_count":23177557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-23T21:41:11.660Z","updated_at":"2025-06-23T21:41:12.503Z","avatar_url":"https://github.com/developmentseed.png","language":"PLpgSQL","readme":"# sat-api-pg\n\n## A Postgres backed STAC API.\n\n[sat-api-pg OpenAPI Docs](http://devseed.com/sat-api-pg-swagger/)\n\nBuilt on the foundation of the excellent\n\n[PostgREST](https://postgrest.com) - Postgres REST API backends.\n\n[PostgREST Starter Kit](https://github.com/subzerocloud/postgrest-starter-kit) - Starter Kit and tooling for authoring REST API backends with PostgREST.\n\n## Purpose\n\nTo provide the community a Postgres backed reference implementation of the [STAC API specification](https://github.com/radiantearth/stac-spec/tree/dev/api-spec).\nPostgres's flexibility and ecosystem of geospatial functionality provide a great\nfoundation for building spatial APIs and we hope the community can expand on this work to drive STAC development forward.\n\n## Project Layout\n\n```bash\n.\n├── db                        # Database schema source files and tests\n│   └── src                   # Schema definition\n│       ├── api               # Api entities avaiable as REST endpoints\n│       ├── data              # Definition of source tables that hold the data\n│       ├── libs              # A collection modules of used throughout the code\n│       ├── authorization     # Application level roles and their privileges\n│       ├── sample_data       # A few sample rows\n│       └── init.sql          # Schema definition entry point\n├── openresty                 # Reverse proxy configurations and Lua code\n│   ├── lualib\n│   │   └── user_code         # Application Lua code\n│   ├── nginx                 # Nginx files\n│   │   ├── conf              # Configuration files\n│   │   └── html              # Static frontend files\n│   ├── Dockerfile            # Dockerfile definition for production\n│   └── entrypoint.sh         # Custom entrypoint\n├── tests                     # Tests for all the components\n│   ├── db                    # pgTap tests for the db\n│   └── rest                  # REST interface tests\n├── docker-compose.yml        # Defines Docker services, networks and volumes\n└── .env                      # Project configurations\n\n```\n\n## Installation\n\n### Prerequisites\n* [Docker](https://www.docker.com)\n* [Node.js](https://nodejs.org/en/)\n* [Yarn](https://yarnpkg.com/lang/en/)\n\nIn the root folder of the application, install the necessary js libs.\n```bash\n$ yarn\n```\n\nThe root folder of the application contains `.sample_env` with development environment settings.  Rename this file by running\n```bash\n$ cp .sample_env .env\n```\n\nIn the root folder of application, run the docker-compose command\n```bash\n$ docker-compose up -d\n```\n\nThe API server will become available at the following endpoint:\n\n- REST [http://localhost:8080](http://localhost:8080)\n\nTry a simple request\n```bash\n$ curl http://localhost:8080/collections/landsat-8-l1/items\n```\n\nTo remove the docker compose stack run\n```bash\n$ docker-compose stop\n```\nFollowed by\n```bash\n$ docker-compose rm\n```\n\n## Development workflow and debugging\n\nIn the root of your project run.\n```bash\n$ yarn subzero dashboard\n```\nAfter this step you can view the logs of all the stack components (SQL queries will also be logged) and\nif you edit a sql / conf / lua file in your project, the changes will immediately be applied.\n\n\n## Testing\nConformance with the [STAC API specification](https://github.com/radiantearth/stac-spec/tree/dev/api-spec) and extensions can be understood by reviewing the integration tests available at `/tests/rest`.\nTo run tests, the `docker-compose` stack must be running.\n\n```bash\nyarn test                   # Run all tests (db, rest)\nyarn test_db                # Run pgTAP tests\nyarn test_rest               # Run integration tests\n```\n\n## Deployment\nFor AWS deployment steps see [deployment/README.md](deployment/README.md).\n\n## Contributing\nThis project was initiated as part of [Development Seed's](https://developmentseed.org/) wider work in helping to build the [STAC API specification](https://github.com/radiantearth/stac-spec/tree/dev/api-spec)\nand open sourced to to the community to help drive contributions and new functionality.  New contributions are welcomed and you can contact\n[@sharkinsspatial](https://github.com/sharkinsspatial) or info@developmentseed.org for additional support or assistance with customization.\nAnyone and everyone is welcome to contribute.\n\n## STAC alignment\nThis API implementation closely follows the [STAC API specification](https://github.com/radiantearth/stac-spec/tree/dev/api-spec).  Becase the STAC API specifcation is under active development there are some current differences between the STAC specification [v0.8.0](https://github.com/radiantearth/stac-spec/releases/tag/v0.8.0).  For more details on capabilities see [sat-api-pg OpenAPI Docs](http://devseed.com/sat-api-pg-swagger/).\nNotable differences\n\n - Though the [search extension](https://github.com/radiantearth/stac-spec/tree/master/api-spec/extensions/search) is not currently implemented much of the same behavior can be acheived via the use of http headers.  When using the `next` and `limit` parameters, responses will contain a `Content-Range` header which shows the current range of the response.  To obtain the total number of items found the request can specify the `Prefer: count=exact` header and the full count will be available in the `Content-Range` response header.  Be aware that this exact count can be slow for very large tables.  For increased performance we will soon release support for the `Prefer: count=planned` header to provide an estimated count.  Note that the accuracy of this count depends on how up-to-date are the PostgreSQL statistics tables.\n\n - The API contains a generic `/items` endpoint which supports access to items across parent collections.  The rationale for this is tied to the insert extension described below.\n\n - The [transaction](https://github.com/radiantearth/stac-spec/tree/master/api-spec/extensions/transaction) is not currently implemented but insert behavior using http POST is enabled for `items` and `collections`.  Authentication for insert operations is handled via the `Authorization` header with JWT tokens.  To make an authenticated request the client must include an Authorization HTTP header with the value `Bearer \u003cjwt\u003e`. Tokens can be generated using the `JWT_SECRET` from the `.env` file by running\n \n ```bash\n $ node generateToken.js \n ```\n\n  Due to permissions on the base table where records are stored insert requests must also set the header `Prefer: return=minimal`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevelopmentseed%2Fsat-api-pg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevelopmentseed%2Fsat-api-pg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevelopmentseed%2Fsat-api-pg/lists"}