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
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:
ancestorsboolean (false), whether to return all the ancestors of the queried locations; if set, an additional field
ancestorswill be included for each result
shapesboolean (false), whether to include the polygon in GeoJSON format with the shape of each location; if set, an additional field
shapewill be included for each result
limitint (0), how many records to return
offsetint (unbounded), offset of the records to be returned, use together with limit for paging.
scopestring (none), all results will be limited to the locations specified in this parameter and their descendants; for example, querying for names beginning with
scope=gadm:USA,gadm:MEXwill return California but not Catamarca
setstring (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
objectstring (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
simplifyfloat (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.
Returns the details of all the locations requested by id.
idsstring, comma separated list of ids
Returns the direct children of the specified location, or all roots if no parent location is specified.
Returns all locations with a name that matches the supplied prefix.
Returns all locations in the service