|
1 | | - |
2 | | -MobilityAPI |
3 | | -=============== |
4 | | -An open source implementation of the [OGC](https://www.ogc.org/) [Moving-Features API](https://ogcapi.ogc.org/movingfeatures/overview.html) based on [MobilityDB](https://github.com/MobilityDB/MobilityDB/) |
5 | | - |
6 | | -<img src="doc/images/mobilitydb-logo.svg" width="200" alt="MobilityDB Logo" /> |
7 | | - |
8 | | -MobilityDB is developed by the Computer & Decision Engineering Department of the [Université libre de Bruxelles](https://www.ulb.be/) (ULB) under the direction of [Prof. Esteban Zimányi](http://cs.ulb.ac.be/members/esteban/). ULB is an OGC Associate Member and member of the OGC Moving Feature Standard Working Group ([MF-SWG](https://www.ogc.org/projects/groups/movfeatswg)). |
9 | | - |
10 | | -<img src="doc/images/OGC_Associate_Member_3DR.png" width="100" alt="OGC Associate Member Logo" /> |
11 | | - |
12 | | -More information about MobilityDB, including publications, presentations, etc., can be found in the MobilityDB [website](https://mobilitydb.com). |
13 | | - |
14 | | -## Introduction |
15 | | -This Python API server provides endpoints for interacting with MobilityDB, a temporal extension for PostgreSQL. It allows users to perform CRUD operations (Create, Read, Update, Delete) on MobilityDB data using HTTP methods. |
16 | | - |
17 | | -## Features |
18 | | -- Supports GET, POST, PUT, and DELETE operations. |
19 | | -- Integrates the PyMEOS library for seamless interaction with MobilityDB. |
20 | | -- Provides endpoints for managing data stored in MobilityDB. |
21 | | - |
22 | | -## Prerequisites |
23 | | -- Linux (ubuntu) |
24 | | -- A recent version of Pyhton |
25 | | - |
26 | | - |
27 | | -## RUN SERVER |
28 | | -- Make script executable: chmod +x run.sh |
29 | | -- Run only the server: ./run.sh |
30 | | -#### RUN SERVER WITH TESTS |
31 | | -- Run with integration tests: ./run.sh --with-tests |
32 | | -(note: this takes a while due to data preprocessing - expect 23 min if the json data file is not present, 21 sec otherwise ) |
33 | | -- If necessary, download ships datasets from: [Denmark Ships DataSets](http://aisdata.ais.dk/?prefix=2024/) aisdk_2024-08-07.zip in data folder |
34 | | -- Manual get requests links on demo.txt |
35 | | -## Usage |
36 | | -Send http requests to the api using any http service. |
37 | | -As an example, your can use the ais.sql that will create ships and ship2 tables containing ships data. |
38 | | -To do that you will have to change the path in the script to the path of your .csv file. |
39 | | -Here is a link to download ships datasets: [Denmark Ships DataSets](http://aisdata.ais.dk/?prefix=2024/) |
40 | | -## Developement |
41 | | -This project is in progress. |
42 | | - |
43 | | -## History and Acknowledgements |
44 | | - |
45 | | -MobilityAPI builds on the foundation laid by **[pg_mfserv](https://github.com/MobilityDB/pg_mfserv)**, an OGC API – Moving Features prototype authored at ULB in early 2024. The pg_mfserv initial implementation provided the Python-server skeleton, the OGC endpoint shape, and the PyMEOS-based MobilityDB integration pattern that MobilityAPI extends with a structured resource layout, comprehensive test coverage, and OGC-conformant request/response handling. |
46 | | - |
47 | | -**pg_mfserv** is preserved in archived form at [`MobilityDB/pg_mfserv`](https://github.com/MobilityDB/pg_mfserv) for historical reference and scholarly attribution; active development continues in this repository. |
48 | | - |
49 | | -Contributors to the lineage, in chronological order: |
50 | | - |
51 | | -- **Maxime Schoemans** ([@mschoema](https://github.com/mschoema)) — pg_mfserv founding author (initial commit, OGC-API endpoint design). |
52 | | -- **Victor Morabito** ([@MrMaxime1er](https://github.com/MrMaxime1er)) — pg_mfserv main developer (column-discovery, request handling, exception handling, route refactors — March 2024). |
53 | | -- **Sirine Meraoui** ([@sirimeraoui](https://github.com/sirimeraoui)) — current MobilityAPI maintainer (structured resource layout, test infrastructure, OGC conformance, documentation). |
54 | | - |
55 | | -See [`AUTHORS.md`](AUTHORS.md) for the complete contributor list. |
56 | | - |
57 | | -## License |
58 | | -##Poetry |
59 | | -poetry install |
60 | | - |
61 | | - |
62 | | - |
| 1 | +MobilityAPI |
| 2 | +=========== |
| 3 | + |
| 4 | +[](LICENSE.txt) |
| 5 | +[](https://www.python.org/) |
| 6 | +[](https://docs.ogc.org/is/22-003r3/22-003r3.html) |
| 7 | + |
| 8 | +An open-source implementation of the [OGC API – Moving Features Standard](https://docs.ogc.org/is/22-003r3/22-003r3.html), built on top of [MobilityDB](https://github.com/MobilityDB/MobilityDB/). |
| 9 | + |
| 10 | +<img src="doc/images/mobilitydb-logo.svg" width="200" alt="MobilityDB Logo" /> |
| 11 | + |
| 12 | +MobilityDB is developed by the Computer & Decision Engineering Department of the [Université libre de Bruxelles (ULB)](https://www.ulb.be/) under the direction of [Prof. Esteban Zimányi](http://cs.ulb.ac.be/members/esteban/). ULB is an OGC Associate Member and member of the OGC Moving Feature Standard Working Group ([MF-SWG](https://www.ogc.org/projects/groups/movfeatswg)). |
| 13 | + |
| 14 | +<img src="doc/images/OGC_Associate_Member_3DR.png" width="100" alt="OGC Associate Member Logo" /> |
| 15 | + |
| 16 | +More information about MobilityDB and the broader MEOS ecosystem can be found at: |
| 17 | + |
| 18 | +- **MobilityDB website** — https://mobilitydb.com |
| 19 | +- **MEOS / libmeos.org** — https://libmeos.org/ (the canonical C library underlying MobilityDB and MobilityDuck; MobilityAPI is one of its [bindings](https://libmeos.org/bindings/mobilityapi/)) |
| 20 | +- **OGC API – Moving Features Standard** — https://docs.ogc.org/is/22-003r3/22-003r3.html |
| 21 | + |
| 22 | +## Introduction |
| 23 | + |
| 24 | +MobilityAPI is a Python API server that exposes MEOS-stored mobility data through the OGC API – Moving Features standard. It provides REST endpoints (GET / POST / PUT / DELETE) over collections of moving features, suitable for HTTP-driven clients that don't speak SQL or the PostgreSQL wire protocol — browser applications, mobile clients, microservices, ETL pipelines. |
| 25 | + |
| 26 | +The reference implementation runs on top of MobilityDB and consumes [PyMEOS](https://github.com/MobilityDB/PyMEOS) for the temporal-data conversion layer. |
| 27 | + |
| 28 | +## Status |
| 29 | + |
| 30 | +This project is under active development. Existing endpoints implement the core OGC API – Moving Features Standard; coverage of the standard is being progressively extended. See [open issues](https://github.com/MobilityDB/MobilityAPI/issues) for the current roadmap and [discussions](https://github.com/MobilityDB/MobilityAPI/discussions) for design conversations. |
| 31 | + |
| 32 | +## Features |
| 33 | + |
| 34 | +- HTTP endpoints implementing the [OGC API – Moving Features Standard](https://docs.ogc.org/is/22-003r3/22-003r3.html): GET / POST / PUT / DELETE on collections, items, temporal geometries, and temporal properties. |
| 35 | +- Built on [PyMEOS](https://github.com/MobilityDB/PyMEOS) for seamless interaction with MobilityDB temporal types. |
| 36 | +- Validation of MovingFeaturesJSON payloads on insert. |
| 37 | +- Test suite ingesting real-world AIS (Automatic Identification System) ship-trajectory data. |
| 38 | + |
| 39 | +## Prerequisites |
| 40 | + |
| 41 | +- Linux (Ubuntu recommended) |
| 42 | +- Python 3.10 or later |
| 43 | +- PostgreSQL with the [MobilityDB](https://github.com/MobilityDB/MobilityDB) extension installed |
| 44 | + |
| 45 | +## Install |
| 46 | + |
| 47 | +```bash |
| 48 | +pip install -r requirements.txt |
| 49 | +``` |
| 50 | + |
| 51 | +## Run the server |
| 52 | + |
| 53 | +```bash |
| 54 | +chmod +x run.sh |
| 55 | +./run.sh |
| 56 | +``` |
| 57 | + |
| 58 | +The server listens on `localhost:8080` by default. Connection parameters live in `config.json`. |
| 59 | + |
| 60 | +## Run with the test suite |
| 61 | + |
| 62 | +```bash |
| 63 | +./run.sh --with-tests |
| 64 | +``` |
| 65 | + |
| 66 | +The test runner ingests an AIS dataset before running the integration tests: |
| 67 | + |
| 68 | +- ~23 minutes on first run if the JSON data file is not yet cached. |
| 69 | +- ~21 seconds on subsequent runs. |
| 70 | + |
| 71 | +If you need the AIS dataset, download `aisdk_2024-08-07.zip` from the [Danish Maritime Authority feed](http://aisdata.ais.dk/?prefix=2024/) into the `data/` folder. Manual GET request examples are in [`demo.txt`](demo.txt). |
| 72 | + |
| 73 | +## Usage |
| 74 | + |
| 75 | +Send HTTP requests to the API using any HTTP client. As an example, the `ais.sql` script will create `ships` and `ship2` tables containing ships data — change the CSV path in the script to point at your downloaded dataset. |
| 76 | + |
| 77 | +## Where MobilityAPI fits |
| 78 | + |
| 79 | +MobilityAPI is the HTTP / OGC layer of the MEOS ecosystem. The other layers are: |
| 80 | + |
| 81 | +- **MEOS** (canonical C library) — the underlying type system and computations. |
| 82 | +- **MobilityDB** and **MobilityDuck** — peer SQL layers (PostgreSQL extension and DuckDB extension respectively) that expose MEOS as first-class database types. |
| 83 | +- **Language bindings** — [PyMEOS](https://github.com/MobilityDB/PyMEOS), [JMEOS](https://github.com/MobilityDB/JMEOS), [meos-rs](https://github.com/MobilityDB/meos-rs), [GoMEOS](https://github.com/MobilityDB/GoMEOS), [MEOS.NET](https://github.com/MobilityDB/MEOS.NET), [MEOS.js](https://github.com/MobilityDB/MEOS.js). |
| 84 | + |
| 85 | +A [longer overview](https://libmeos.org/) is available on libmeos.org. |
| 86 | + |
| 87 | +## Contributing |
| 88 | + |
| 89 | +See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup, test instructions, code style, and PR conventions. Issues and pull requests are welcome. |
| 90 | + |
| 91 | +## History and Acknowledgements |
| 92 | + |
| 93 | +MobilityAPI builds on the foundation laid by **[pg_mfserv](https://github.com/MobilityDB/pg_mfserv)**, an OGC API – Moving Features prototype authored at ULB in early 2024. The pg_mfserv initial implementation provided the Python-server skeleton, the OGC endpoint shape, and the PyMEOS-based MobilityDB integration pattern that MobilityAPI extends with a structured resource layout, comprehensive test coverage, and OGC-conformant request/response handling. |
| 94 | + |
| 95 | +**pg_mfserv** is preserved in archived form at [`MobilityDB/pg_mfserv`](https://github.com/MobilityDB/pg_mfserv) for historical reference and scholarly attribution; active development continues in this repository. |
| 96 | + |
| 97 | +Contributors to the lineage, in chronological order: |
| 98 | + |
| 99 | +- **Maxime Schoemans** ([@mschoema](https://github.com/mschoema)) — pg_mfserv founding author (initial commit, OGC-API endpoint design). |
| 100 | +- **Victor Morabito** ([@MrMaxime1er](https://github.com/MrMaxime1er)) — pg_mfserv main developer (column-discovery, request handling, exception handling, route refactors — March 2024). |
| 101 | +- **Sirine Meraoui** ([@sirimeraoui](https://github.com/sirimeraoui)) — current MobilityAPI maintainer (structured resource layout, test infrastructure, OGC conformance, documentation). |
| 102 | + |
| 103 | +See [`AUTHORS.md`](AUTHORS.md) for the complete contributor list. |
| 104 | + |
| 105 | +## License |
| 106 | + |
| 107 | +MobilityAPI is released under [The PostgreSQL License](LICENSE.txt). If you use MobilityAPI in academic or technical work, please cite it using the metadata in [`CITATION.cff`](CITATION.cff). |
0 commit comments