Public Repository

Last pushed: 3 years ago
Short Description
InSTEDD Location Service
Full Description

InSTEDD Location Service

InSTEDD Location Service hosts locations information from different sources, and provides a simple HTTP API for querying them based on multiple criteria.


This image is based on Phusion Baseimage for starting the API service and running the migrations on startup. Code is built on a separate image and then moved, refer to the project's Makefile for more info.


The service uses a PostgreSQL backend that is configured in db/dbconf.yml. Default database name is location_service. Migrations are managed via goose, and are executed by running bin/goose up.


Data can be imported from multiple data sources via the executable bin/importer. Run the executable for more info on the accepted options.

The following data sources are currently supported:

  • GADM shapefiles
  • Natural Earth shapefiles


API server is started via bin/api, optionally providing a -port XXXX flag to start on a specific port (8080 by default). All endpoints are queried via HTTP GET and provide responses in JSON format.

All endpoints can be invoked with the following optional parameters:

  • ancestors boolean (false), whether to return all the ancestors of the queried locations; if set, an additional field ancestors will be included for each result
  • shapes boolean (false), whether to include the polygon in GeoJSON format with the shape of each location; if set, an additional field shape will be included for each result
  • limit int (0), how many records to return
  • offset int (unbounded), offset of the records to be returned, use together with limit for paging.
  • scope string (none), all results will be limited to the locations specified in this parameter and their descendants; for example, querying for names beginning with Ca with scope=gadm:USA,gadm:MEX will return California but not Catamarca
  • set string (none), which locations set to query; for example, if a server contains both GADM and NaturalEarth data, the search can be restricted to the latter by specifying set=ne.
  • object string (none), if set, will return a map of locations, indexed by their ids, nested within the key with name object, useful for supplying locations with the format expected by notifiable-diseases; if not set, will return an array
  • simplify float (none), if set, shapes will be dynamically simplified using this value as tolerance (higher values imply a higher simplification); note that this is an expensive operation to perform, and overly complex shapes are already cached in a simplified version, so this parameter is often unneeded


Returns all leaf locations that contain the specified point.

  • x float
  • y float


Returns the details of all the locations requested by id.

  • ids string, comma separated list of ids


Returns the direct children of the specified location, or all roots if no parent location is specified.

  • id string


Returns all locations with a name that matches the supplied prefix.

  • name string


Returns all locations in the service

Docker Pull Command