This repository contains the public documentation for SpatiaFi. Feel free to use notebooks, scripts, and other resources in this repository to help you get started with SpatiaFi!

⭐Note for SpatiaFi employees: This repository is automatically incorporated into the private docs repo spfi-docs-build and deployed to docs.spatiafi.com

The best place to start is the SpatiaFi API Quickstart notebook. This notebook will walk you through the process of authenticating with the SpatiaFi API and downloading data.

The SpatiaFi API is a RESTful API that allows you to query and download data from the SpatiaFi database. The API is available at api.spatiafi.com.

Authentication is OAuth2. Because it is standardized, most languages will have an authentication library that should be used instead of manual interaction. For Python, we recommend the library Authlib.

In most cases the SpatiaFi API returns data in GeoJSON format. GeoJSON is a standard format for representing geospatial data. It is a text-based format that is easy to read and write. GeoJSON is supported by most GIS software and libraries.

We welcome contributions to this repository. If you have a suggestion for a new notebook, script, or other resource, please open an issue or submit a pull request. All contributions must be made under the MIT License.

The notebooks in this repository are used for two purposes:

• Generating examples for the SpatiaFi API documentation site
• Automated testing of the SpatiaFi API

Because of this, notebooks must follow a few strict guidelines:

The notebooks must be able to run in a minimal Jupyter environment such as Google Colab or Binder without assuming that any additional Python packages are installed. Many geospaital Python packages such as GDAL, Cartopy, etc. are not pre-installed in these environments.

To work around this, Python packages (and Ubuntu apt packages) used in the notebooks must be installed in the notebook itself.

To install Python packages in a notebook, use the %pip magic command at the top of the notebook. A single %pip command can be used to install multiple packages:

%pip install <package1> <package2> ...

To install Ubuntu packages in a notebook, use the !sudo apt install <package1> command at the top of the notebook.

Before being published on the SpatiaFi API documentation site, the notebooks must successfully run using the jupyter/scipy-notebook Docker image provided by Jupyter Docker Stacks. This image includes many common Python packages used for scientific computing, but notably does not include GDAL or other geospatial packages.

To test that a notebook runs successfully in the jupyter/scipy-notebook image, the test-notebook.sh script has been provided. To run this script, you must have Docker installed.

./test-notebook.sh notebooks/<notebook>.ipynb

If ./test-notebook.sh is run without any arguments, it will test all notebooks in the notebooks/ directory.

Jupyter Notebooks in this repository must not have any cell outputs. This is because the notebooks are run automatically as part of the build process, to ensure that they are up-to-date and error-free. Outputs should be stripped out before committing notebooks to the repository. This can be done with the following command:

nbstripout notebooks/*.ipynb

Alternatively, you can use the pre-commit hook described below.

While not required, we recommend installing nbdime to help with notebook diffs. Then enable nbdime for git:

nbdime config-git --enable --global

CI/CD workflows are defined in an internal private repo.

We acknowledge that contributors may have a limited view of these builds. If this causes a problem for you please feel free to contact the maintainers of this project, and we'll be happy to help.

We use pre-commit to run code formatting and linting before commits are made. This ensures that all code in the repository is formatted consistently.

Please install pre-commit before making any commits:

pip install pre-commit
pre-commit install

Jupyter Notebooks must pass the following pre-commit hooks:

• nbstripout - Remove notebook outputs before committing
• black - Python code formatter
• isort - Python import sorter
• ruff - Python linter and formatter
• mdformat - Markdown linter

This repository is licensed under the MIT License. You are free to use the resources in this repository as starting points for your own projects.

If you have any questions, please open a GitHub Issue or contact us at [email protected].