diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md new file mode 100644 index 0000000..57357df --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -0,0 +1,36 @@ +--- +name: Bug report +about: Report unexpected behaviour, errors, or test failures +title: "[BUG] " +labels: bug +--- + +## Description + +Brief description of the bug. + +## Steps to reproduce + +1. ... +2. ... +3. ... + +## Expected behaviour + +What you expected to happen. + +## Actual behaviour + +What actually happened. Include error messages, stack traces, or response bodies as appropriate. + +## Environment + +- MobilityAPI version / commit: +- Python version: +- PostgreSQL version: +- MobilityDB version: +- OS: + +## Additional context + +Anything else that might help — minimal reproducer, related issues, OGC API – Moving Features specification reference if relevant. diff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.md new file mode 100644 index 0000000..70b4235 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.md @@ -0,0 +1,22 @@ +--- +name: Feature request +about: Suggest a new endpoint, OGC-conformance improvement, or backend integration +title: "[FEAT] " +labels: enhancement +--- + +## Motivation + +What problem does this feature solve, or what use case does it enable? + +## Proposed change + +A clear description of the new endpoint, behaviour, or integration. If it relates to the OGC API – Moving Features standard, link to the relevant section: https://docs.ogc.org/is/22-003r3/22-003r3.html + +## Alternatives considered + +Other approaches you considered and why this one is preferable. + +## Additional context + +Related issues, references, or examples from sister projects (PyMEOS, JMEOS, MobilityDB, MobilityDuck). diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..7f8afd7 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,22 @@ +## Summary + +Brief description of what this PR does and why. + +## Changes + +- ... + +## Related issues + +Fixes #N / Refs #N + +## Testing + +How you verified the change. Output of `./run.sh --with-tests` for substantive changes; for documentation-only changes a description of what you read suffices. + +## Checklist + +- [ ] Tests pass locally +- [ ] `ruff check .` passes +- [ ] Documentation updated where relevant +- [ ] Entries in `AUTHORS.md` / `CITATION.cff` updated if this is a first-time substantial contribution diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml new file mode 100644 index 0000000..341f4eb --- /dev/null +++ b/.github/workflows/python.yml @@ -0,0 +1,41 @@ +name: Python checks + +on: + pull_request: + push: + branches: [master] + +jobs: + lint: + name: Lint (ruff) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.11" + - name: Install ruff + run: pip install ruff + - name: Run ruff + run: ruff check . || echo "::warning::ruff found issues — please fix before merging" + continue-on-error: true + + python-import: + name: Import smoke test + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.11" + - name: Install dependencies + run: | + pip install --upgrade pip + pip install -r requirements.txt + - name: Verify modules import + run: | + python -c "import server" || true + python -c "import utils" + python -c "from resource.collections import Create, Retrieve" + python -c "from resource.moving_features import Create, Retrieve" + python -c "from resource.temporal_geom_query import distance, velocity, acceleration" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ddfda3c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,72 @@ +# Contributing to MobilityAPI + +Thank you for considering a contribution to MobilityAPI. This document covers how to set up a development environment, run the tests, and the conventions we follow when filing issues and pull requests. + +## Development setup + +### Prerequisites + +- **Python 3.10** or later +- **PostgreSQL** with the [MobilityDB](https://github.com/MobilityDB/MobilityDB) extension installed +- A working clone of this repository + +### Install dependencies + +```bash +pip install -r requirements.txt +``` + +### Configure the database connection + +Edit `config.json` (or set the corresponding environment variables) to point at your local PostgreSQL + MobilityDB instance. + +### Run the server + +```bash +chmod +x run.sh +./run.sh +``` + +The server listens on `localhost:8080` by default. + +## Running the tests + +```bash +./run.sh --with-tests +``` + +The test runner ingests an AIS dataset before running the integration tests. Expect ~23 minutes on first run if the JSON data file is not yet cached, ~21 seconds on subsequent runs. + +## Filing issues + +Please use the issue templates under `.github/ISSUE_TEMPLATE/`: + +- **Bug report** — for unexpected behaviour, errors, or test failures. +- **Feature request** — for new endpoints, OGC-compliance improvements, or integration with other backends. + +Include the smallest reproducible example you can. For OGC-conformance issues, please reference the relevant section of the [OGC API – Moving Features Standard](https://docs.ogc.org/is/22-003r3/22-003r3.html). + +## Pull requests + +- Branch from `master`. Use a descriptive branch name (`fix/`, `feat/`, `refactor/` prefix is encouraged). +- Keep PRs focused — one logical change per PR. +- Use the PR template under `.github/PULL_REQUEST_TEMPLATE.md`. +- Verify tests pass locally before opening the PR. +- Reference any related issues with `Fixes #N` or `Refs #N` in the description. + +## Code style + +Python source follows [PEP 8](https://peps.python.org/pep-0008/). The CI runs `ruff check` on every PR — please run it locally before pushing: + +```bash +pip install ruff +ruff check . +``` + +## Lineage + +MobilityAPI builds on the foundation of [pg_mfserv](https://github.com/MobilityDB/pg_mfserv), an OGC API – Moving Features prototype authored at ULB in 2024. See [`AUTHORS.md`](AUTHORS.md) for the contributor history across both phases of the project. + +## License + +By contributing, you agree that your contributions will be licensed under the project's [PostgreSQL License](LICENSE.txt). diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..328dcad --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,16 @@ +------------------------------------------------------------------------------- +This MobilityAPI code is provided under The PostgreSQL License. + +Copyright (c) 2024, Université libre de Bruxelles and MobilityAPI contributors + +Permission to use, copy, modify, and distribute this software and its documentation for any purpose, without fee, and without a written agreement is hereby +granted, provided that the above copyright notice and this paragraph and the following two paragraphs appear in all copies. + +IN NO EVENT SHALL UNIVERSITE LIBRE DE BRUXELLES BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST +PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF UNIVERSITE LIBRE DE BRUXELLES HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGE. + +UNIVERSITE LIBRE DE BRUXELLES SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND UNIVERSITE LIBRE DE BRUXELLES HAS NO OBLIGATIONS TO PROVIDE +MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. +------------------------------------------------------------------------------- diff --git a/README.md b/README.md index 8f8dafa..dc786c0 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,107 @@ - -MobilityAPI -=============== -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/) - -MobilityDB Logo - -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)). - -OGC Associate Member Logo - -More information about MobilityDB, including publications, presentations, etc., can be found in the MobilityDB [website](https://mobilitydb.com). - -## Introduction -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. - -## Features -- Supports GET, POST, PUT, and DELETE operations. -- Integrates the PyMEOS library for seamless interaction with MobilityDB. -- Provides endpoints for managing data stored in MobilityDB. - -## Prerequisites -- Linux (ubuntu) -- A recent version of Pyhton - - -## RUN SERVER -- Make script executable: chmod +x run.sh -- Run only the server: ./run.sh -#### RUN SERVER WITH TESTS -- Run with integration tests: ./run.sh --with-tests -(note: this takes a while due to data preprocessing - expect 23 min if the json data file is not present, 21 sec otherwise ) -- If necessary, download ships datasets from: [Denmark Ships DataSets](http://aisdata.ais.dk/?prefix=2024/) aisdk_2024-08-07.zip in data folder -- Manual get requests links on demo.txt -## Usage -Send http requests to the api using any http service. -As an example, your can use the ais.sql that will create ships and ship2 tables containing ships data. -To do that you will have to change the path in the script to the path of your .csv file. -Here is a link to download ships datasets: [Denmark Ships DataSets](http://aisdata.ais.dk/?prefix=2024/) -## Developement -This project is in progress. - -## History and Acknowledgements - -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. - -**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. - -Contributors to the lineage, in chronological order: - -- **Maxime Schoemans** ([@mschoema](https://github.com/mschoema)) — pg_mfserv founding author (initial commit, OGC-API endpoint design). -- **Victor Morabito** ([@MrMaxime1er](https://github.com/MrMaxime1er)) — pg_mfserv main developer (column-discovery, request handling, exception handling, route refactors — March 2024). -- **Sirine Meraoui** ([@sirimeraoui](https://github.com/sirimeraoui)) — current MobilityAPI maintainer (structured resource layout, test infrastructure, OGC conformance, documentation). - -See [`AUTHORS.md`](AUTHORS.md) for the complete contributor list. - -## License -##Poetry -poetry install - - - +MobilityAPI +=========== + +[![License: PostgreSQL](https://img.shields.io/badge/License-PostgreSQL-blue.svg)](LICENSE.txt) +[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/) +[![OGC API – Moving Features](https://img.shields.io/badge/OGC%20API-Moving%20Features-green.svg)](https://docs.ogc.org/is/22-003r3/22-003r3.html) + +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/). + +MobilityDB Logo + +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)). + +OGC Associate Member Logo + +More information about MobilityDB and the broader MEOS ecosystem can be found at: + +- **MobilityDB website** — https://mobilitydb.com +- **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/)) +- **OGC API – Moving Features Standard** — https://docs.ogc.org/is/22-003r3/22-003r3.html + +## Introduction + +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. + +The reference implementation runs on top of MobilityDB and consumes [PyMEOS](https://github.com/MobilityDB/PyMEOS) for the temporal-data conversion layer. + +## Status + +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. + +## Features + +- 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. +- Built on [PyMEOS](https://github.com/MobilityDB/PyMEOS) for seamless interaction with MobilityDB temporal types. +- Validation of MovingFeaturesJSON payloads on insert. +- Test suite ingesting real-world AIS (Automatic Identification System) ship-trajectory data. + +## Prerequisites + +- Linux (Ubuntu recommended) +- Python 3.10 or later +- PostgreSQL with the [MobilityDB](https://github.com/MobilityDB/MobilityDB) extension installed + +## Install + +```bash +pip install -r requirements.txt +``` + +## Run the server + +```bash +chmod +x run.sh +./run.sh +``` + +The server listens on `localhost:8080` by default. Connection parameters live in `config.json`. + +## Run with the test suite + +```bash +./run.sh --with-tests +``` + +The test runner ingests an AIS dataset before running the integration tests: + +- ~23 minutes on first run if the JSON data file is not yet cached. +- ~21 seconds on subsequent runs. + +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). + +## Usage + +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. + +## Where MobilityAPI fits + +MobilityAPI is the HTTP / OGC layer of the MEOS ecosystem. The other layers are: + +- **MEOS** (canonical C library) — the underlying type system and computations. +- **MobilityDB** and **MobilityDuck** — peer SQL layers (PostgreSQL extension and DuckDB extension respectively) that expose MEOS as first-class database types. +- **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). + +A [longer overview](https://libmeos.org/) is available on libmeos.org. + +## Contributing + +See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup, test instructions, code style, and PR conventions. Issues and pull requests are welcome. + +## History and Acknowledgements + +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. + +**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. + +Contributors to the lineage, in chronological order: + +- **Maxime Schoemans** ([@mschoema](https://github.com/mschoema)) — pg_mfserv founding author (initial commit, OGC-API endpoint design). +- **Victor Morabito** ([@MrMaxime1er](https://github.com/MrMaxime1er)) — pg_mfserv main developer (column-discovery, request handling, exception handling, route refactors — March 2024). +- **Sirine Meraoui** ([@sirimeraoui](https://github.com/sirimeraoui)) — current MobilityAPI maintainer (structured resource layout, test infrastructure, OGC conformance, documentation). + +See [`AUTHORS.md`](AUTHORS.md) for the complete contributor list. + +## License + +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).