Canonicalisation bundle: LICENSE, CI, contributor scaffolding, README rewrite

.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.

.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).

.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

.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"

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).

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.  
+-------------------------------------------------------------------------------

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/)
-
-<img src="doc/images/mobilitydb-logo.svg" width="200" alt="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)).
-
-<img src="doc/images/OGC_Associate_Member_3DR.png" width="100" alt="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/).
+
+<img src="doc/images/mobilitydb-logo.svg" width="200" alt="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)).
+
+<img src="doc/images/OGC_Associate_Member_3DR.png" width="100" alt="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).