Open Topo Data Server Documentation
Getting started
The easiest way to run Open Topo Data is with Docker. Install docker then run the following commands:
git clone https://github.com/ajnisbet/opentopodata.git
cd opentopodata
make build
make run
This will start a server on localhost:5000
with a small demo dataset called test-dataset
. Check out the API docs for info about the format of requests and responses.
Getting started on Windows
On Windows you'll probably need to run the build and run commands without make:
git clone https://github.com/ajnisbet/opentopodata.git cd opentopodata docker build --tag opentopodata --file docker/Dockerfile . docker run --rm -it --volume C:/path/to/opentopodata/data:/app/data:ro -p 5000:5000 opentopodata sh -c "/usr/bin/supervisord -c /app/docker/supervisord.conf"
For more details see this note on windows support.
Dataset support
Open Topo Data supports all georeferenced raster formats supported by GDAL (e.g, .tiff
, .hgt
, .jp2
).
Datasets can take one of two formats:
- A single raster file.
- A collection of square raster tiles which follow the SRTM naming convention: the file is named for the lower left corner. So a file named
N30W120.tiff
would span from 30 to 31 degrees latitude, and -120 to -119 degrees longitude. By default tiles are 1° by 1° and the coordinates are in WGS84, but this can be configured.
If your dataset consists of multiple files that aren't on a nice grid, you can create a .vrt
file pointing to the files that Open Topo Data will treat as a single-file dataset. For an example of this process, see the documentation for configuring EMODnet.
Configuration
Open Topo Data is configured by a config.yaml
file. If that file is missing it will look for example-config.yaml
instead.
A config might look like:
max_locations_per_request: 100 access_control_allow_origin: '*' datasets: - name: etopo1 path: data/etopo1/ - name: srtm90m path: data/srtm-90m-v3/ filename_epsg: 4326 filename_tile_size: 1
corresponding to a directory structure:
opentopodata | └───data | ├───etopo1 | | | └───etopo1-dem.geotiff | └───srtm-90m-v3 | ├───N00E000.hgt ├───N00E001.hgt ├───N00E002.hgt ├───etc...
which would expose localhost:5000/v1/etopo1
and localhost:5000/v1/srtm90m
.
Config spec
max_locations_per_request
: Requests with more than this many locations will return a 400 error. Default:100
.access_control_allow_origin
: Value for theAccess-Control-Allow-Origin
CORS header. Set to*
or a domain to allow in-browser requests from a different origin. Set tonull
to send noAccess-Control-Allow-Origin
header. Default:null
.datasets[].name
: Dataset name, used in url. Required.datasets[].path
: Path to folder containing the dataset. If the dataset is a single file it must be placed inside a folder. This path is relative to the repository directory inside docker. I suggest placing datasets inside the provideddata
folder, which is mounted in docker bymake run
. Files can be nested arbitrarily inside the dataset path. Required.datasets[].filename_epsg
: For tiled datasets, the projection of the filename coordinates. The default value is4326
, which is latitude/longitude with the WGS84 datum.datasets[].filename_tile_size
: For tiled datasets, how large each square tile is, in the units offilename_epsg
. For example, a lat,lon location of38.2,121.2
would lie in the tileN38W121
for a tile size of 1, but lie inN35W120
for a tile size of 5. Default:1
.
Adding datasets
An important goal of Open Topo Data is make is easy to add new datasets. The included dataset is very low resolution (about 100km) and is intended only for testing.
Adding a new dataset takes two steps:
- placing the dataset in the
data
directory - adding the path to the dataset in
config.yaml
.
Instructions are provided for adding the various datasets used in the public API: