Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Application Programming Interface (API)
Clone this wiki locally
Introduction to the database
The NESCent working group, Synthesizing and databasing fossil calibrations: divergence dating and beyond, has developed a database of fossil calibrations for use in molecular divergence time analysis. The database is coupled to a publication stream for fossil calibration papers in Palaeontologia Electronica. These papers follow the best practice guidelines for justifying fossil calibrations (Parham et al).
The Fossil Calibrations database is nearing launch. In addition to its Web UI, we're building a simple API to provide access to calibration data in CSV and JSON formats. We're seeking feedback from potential users on how you'd like to use this API.
The primary organization unit in the database is a calibration, which contains information about age, phylogenetic placement and supporting fossils. The API is therefore organized around search and download of calibrations. The first version will focus on filtering/searching of calibrations by their age and position in the tree, but there are still key decisions to be made.
- Database URL: http://fossilcalibrations.org
- Source code: https://github.com/NESCent/FossilCalibrations
- GitHub issue for feedback: https://github.com/NESCent/FossilCalibrations/issues/73
Please contact Karen Cranston for login information, if you have not already received this information by email
One approach is to adopt RESTful URLs and parameters, mapping resources and queries onto documented, structured paths. For example,
This query would return the calibrations in the database, associated with the geological time period 'Neogene'. The list of geological times would be available at /api/v1/geologicalTimes/. Another example,
would fetch all calibrations attached to nodes within the Primates clade, and return them in CSV format.
The other proposed parameters are documented at http://docs.fcdb.apiary.io/
Another approach is to adopt a standard query language, like CQL. This still requires knowing the nouns, but handles the structure more simply:
/api/v1/calibrations?q="geologicalTime = Neogene" /api/v1/calibrations?q="minAge > 10 and maxAge < 35”
In this case, the query string would need to be URI escaped to handle spaces/quotes. Additional searches (e.g. fulltext, by publication, etc.) wouldn’t require any new URLs once they are implemented.
Questions for potential users:
- How would you imagine primarily using this database?
- Do you prefer one of the two formats (documented parameters or CQL), and why?
- Do the initial search modes (age and tree position) make this a usable API? If not, why not? What are we missing?