· Matthias Berger
A Movebank API on Your Own Computer
"Can't my scripts just read the mirror?"
In the first post of this series we copied Movebank studies to our own disk: JSON for the metadata, CSV for the events, updated incrementally. That's a good start, but most tools don't read folders. The R packages move and move2, our Java client, and many home-grown scripts talk to the Movebank REST API. They send a request to movebank.org and expect Movebank's answer, down to the format of every field.
So we gave the mirror the same API.
movebank-mirror-api in one sentence
movebank-mirror-api is a small read-only server that answers Movebank API requests from your local mirror, so a tool that talks to movebank.org can talk to your copy instead.
Movebank API ──► movebank-mirror ──► <mirror-dir>/ ──► movebank-mirror-api ◄── your tools
(copies to disk) (answers like Movebank)
It is deliberately not a Movebank clone: no database, no user interface, no data upload, no accounts. It reads the files movebank-mirror wrote and answers the read requests that analysis tools actually make: studies, tags, individuals, deployments, sensors, attribute lists and, above all, events.
Getting started
You need Java 21 and a mirror directory from part 1. Download the release from GitHub and start the server on your mirror:
tar -xf movebank-mirror-api-boot-0.0.3.tar
./movebank-mirror-api-boot-0.0.3/bin/movebank-mirror-api -d /var/lib/mvb
It listens on http://localhost:8080/movebank. Ask it what it has, exactly as you would ask Movebank:
# all studies in the mirror
curl 'http://localhost:8080/movebank/service/direct-read?entity_type=study'
# the GPS events of the Galapagos albatross study from part 1
curl 'http://localhost:8080/movebank/service/direct-read?entity_type=event&study_id=2911040&sensor_type_id=653'
To point a tool at your mirror, change its base URL from https://www.movebank.org/movebank to http://localhost:8080/movebank. With our Java client movebank-api-client that's the first argument:
MovebankApiClient client = new MovebankApiClient(
"http://localhost:8080/movebank",
"ignored", "ignored", // the server doesn't check credentials
html -> true);
Everything else in your code stays as it is.
How close is it to the real thing?
"Speaks the same API" is easy to claim. Clients notice small differences: whether a missing value is empty or NA, how lines end, which deployment an event belongs to, the order of the rows. So we measured: the same requests that move and move2 send, once to movebank.org and once to the mirror, and compared the answers.
Some of what that turned up:
- Missing values are empty, not
NA. - Lines end in CRLF, as Movebank sends them.
- An event belongs to a deployment if it falls between
deploy_onanddeploy_off; a blank bound is open. With this rule the deployment of every one of the 114,929 events in the albatross study matches Movebank. - Rows come in Movebank's order: by sensor type, then individual, then time, merged across all tags an animal carried.
A plain GPS request for one individual now returns byte for byte what Movebank returns. For the request move makes, the only difference left is that Movebank puts quotes around text values. Each release is checked with move and move2 against the mirror: version 0.0.3 passes 4 of 4 checks with both. Every quirk the server reproduces on purpose is written down in BUG_COMPATIBILITY.md, because code that looks strange there is usually what keeps a client working.
What it doesn't do (yet)
The server covers what analysis tools use most. The rest, from the project's to-do list:
sortandlimitare ignored.attributes=allon events lacks four columns Movebank adds from its own tables (study id, the local identifiers of individual and tag, the taxon). Neithermovenormove2needs them.- The column order of events differs from Movebank's. Clients that read columns by name don't notice; clients that count positions would.
- No authentication. Usernames and passwords are accepted and ignored.
Keep it on your computer
Because there is no authentication, the server only listens on your own machine (127.0.0.1) unless you tell it otherwise. If you open it to a network, put a proxy with a login in front of it.
The same goes for the data: your mirror holds studies you were allowed to download, under the terms you accepted. Serving them through a local API doesn't change those terms. Keep other people's data where the study's licence allows it to be.
What's Next?
The server is the bridge. In the next post we walk across it with R: move2 and move reading your mirror instead of movebank.org, with a single setting in move2 and a small shim for move.
Building your own tracking database instead? Our series Basics of Animal Tracking Databases starts with the data model. Questions or a use case we haven't thought of? Get in touch.
About the Author
Matthias Berger has been a key member of the Movebank Development Team since its inception in 2008, contributing to the advancement of animal tracking databases and supporting researchers worldwide.
