Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

EarthLife Consortium API (api_v1)

For the live version of this API visit and choose API Sandbox from the menu on the left. The full documentation is also available from this site to enable direct query of the operational data service.


The ELC API is a composite api which generates and dispaches queries for the Neotoma and Paleobiology (PBDB)
databases using a simplified, common resource retrival specification. Results are returned as aggregated JSON objects.

This project follows an "API first" development process where:

  • The interface schema, complient with the OpenAPI (formally known as Swagger) version 2.0 specification, is first defined.
  • Server stubs are generated from this definition.
  • Routing is automatically handled by a Swagger complient interface library.
  • Finally the server backend code is developed for each generated function.
  • Changes to the API can be made in the schema during development and the changes pushed down through the code.
  • A Swagger HTML5 based user interface is also generated for browsing the API documentation and testing the parameter calls.


Development team:

Technical Description

The API has been developed with the following modern open source tools:

  • Python
  • Flask (Python micro web framework)
  • Connexion (Flask based routing library that is complient with OpenAPI 2.0)
  • Requests (HTTP library for Python)
  • git (for version control) and GitHub (for repository hosting and issue tracking) Optionally
  • swagger-codegen (Java based templating engine which can use Flask+Connexion to generate the server)
  • swagger-edit (a Node.js based editor and validator for OpenAPI spec YAML files)

Starting and Building the API

The API requires Python 3.5 or greater. To run the server, first install Connexion from the Cheese Shop (PyPI). This also installs Flask if it is not already installed:

pip3 install -r requirements.txt
python3 -m swagger_server

The api documentation and user interface will be available at:

The raw OpenAPI definition is at:

To initially build the server and generate controller stubs we used swagger-codegen. This is not required if you are simply cloning this repository.

swagger-codegen generate -i ./swagger.yaml -l python-flask -o [your

Error reporting

The API reports all excemptions as serialized JSON strictly conforming to the Internet Engineering Task Force IETF standard

Production Environment

See README-Deploy for informaton regarding production deployment as a uWSGI app.