Update README.md

mfdz · Jan 23, 2025 · 19d553e · 19d553e
1 parent c7a19b8
commit 19d553e
Showing 1 changed file with 129 additions and 18 deletions.
diff --git a/README.md b/README.md
@@ -32,39 +32,150 @@ Example (`by.json`):
 {"id": "by", "bbox": [ 8.97, 47.28, 13.86, 50.56]}
 ``` -->
 
+## 2. Configure the enhancer URL for Amarillo
 
-### Uvicorn configuration
-
-`amarillo-enhancer` uses `uvicorn` to run. Uvicorn can be configured as normal by passing in arguments such as `--port 8001` to change the port number.
+When Amarillo receives a new carpool object, after returning an OK response it will make a request to the enhancer configured through the environment variable `enhancer_url`. By default it points to `'http://localhost:8001'`.
 
 ### Graphhopper
 
 `amarillo-enhancer` uses a Graphhopper service for routing. You can configure the service that is used with the environment variable `graphhopper_base_url`. By default it is `https://api.mfdz.de/gh'`
 
-## 2. Make requests to the enhancer
+# Running in development
 
-To enhance a trip, make a POST request to  `/` with the carpool data as the body. The enhancer will respond with the same carpool object enhanced with additional stop time and path data. The enhancer does not save the generated file.
+- Python 3.10 with pip
+- python3-venv
 
-## 3. Configure the enhancer URL for Amarillo
+Create a virtual environment:
+`python3 -m venv venv`.
 
-When Amarillo receives a new carpool object, after returning an OK response it will make a request to the enhancer configured through the environment variable `enhancer_url`. By default it points to `'http://localhost:8001'`.
+Activate the environment:
+`. venv/bin/activate`
 
-# Run with uvicorn
+Install the dependencies: `pip install -r requirements.txt`.
 
-- Python 3.10 with pip
-- python3-venv
+Run with `uvicorn amarillo-enhancer.enhancer:app`. 
+
+In development, you can use `--reload`. Uvicorn can be configured as normal by passing in arguments such as `--port 8001` to change the port number.
 
-Create a virtual environment `python3 -m venv venv`.
+# Running with docker
 
-Activate the environment and install the dependencies `pip install -r requirements.txt`.
+For running a production instance of Amarillo and Amarillo-enhancer together, use [amarillo-compose](https://github.com/mfdz/amarillo-compose).
 
-Run `uvicorn amarillo-enhancer.enhancer:app`. 
+Otherwise, you can build and run a local version in docker:
+```bash
+docker build -t amarillo-enhancer .
+docker run -it --rm --name amarillo-enhancer -p 8001:80 -e TZ=Europe/Berlin -v $(pwd)/data:/app/data amarillo-enhancer```
+```
 
-In development, you can use `--reload`. 
 
-# Run with docker
-You can download a container image from the [MFDZ package registry](https://github.com/orgs/mfdz/packages?repo_name=amarillo-gtfs-generator).
 
-Example command:
+## Making requests to the enhancer
+
+To enhance a trip, make a POST request to  `/` with the carpool data as the body. The enhancer will respond with the same carpool object enhanced with additional stop time and path data. The enhancer does not save the generated file.
+
+Example:
+
 ```bash
-docker run -it --rm --name amarillo-gtfs-generator -p 8002:80 -e TZ=Europe/Berlin -v $(pwd)/data:/app/data amarillo-gtfs-generator```
+
+curl -X 'POST' \
+  'http://localhost:8001/' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "id": "1234",
+  "agency": "mfdz",
+  "deeplink": "http://mfdz.de",
+  "stops": [
+    {
+      "name": "Stuttgart",
+      "lat": 48.775845,
+      "lon": 9.182932
+    },
+    {
+      "name": "Mannheim",
+      "lat": 49.487457,
+      "lon": 8.466040
+    }
+  ],
+  "departureTime": "12:34",
+  "departureDate": "2025-01-30",
+  "lastUpdated": "2025-01-23T12:34:00+00:00"
+}'
+
+```
+
+Should return a response with additional stops, stop times and coordinates in the carpool data:
+
+```jsonc
+
+{
+    "id": "1234",
+    "agency": "mfdz",
+    "deeplink": "http://mfdz.de/",
+    "stops": [
+        {
+            "id": "de:08111:6075",
+            "name": "Stuttgart, Charlottenplatz",
+            "departureTime": "12:34:00",
+            "arrivalTime": "12:34:00",
+            "lat": 48.776276,
+            "lon": 9.182911,
+            "pickup_dropoff": "only_pickup"
+        },
+        {
+            "id": "de:08111:6023",
+            "name": "Stuttgart, Dorotheenstraße",
+            "departureTime": "12:34:09",
+            "arrivalTime": "12:34:09",
+            "lat": 48.775234,
+            "lon": 9.181959,
+            "pickup_dropoff": "only_pickup"
+        },
+        // ... other stops
+        {
+            "id": "de:08222:2395",
+            "name": "Mannheim, Am Friedrichsplatz",
+            "departureTime": "13:54:51",
+            "arrivalTime": "13:54:51",
+            "lat": 49.482642,
+            "lon": 8.479252,
+            "pickup_dropoff": "only_dropoff"
+        },
+        {
+            "id": "de:08222:2459",
+            "name": "Mannheim, Rosengarten",
+            "departureTime": "13:55:30",
+            "arrivalTime": "13:55:30",
+            "lat": 49.485449,
+            "lon": 8.475398,
+            "pickup_dropoff": "only_dropoff"
+        }
+    ],
+    "departureTime": "12:34:00",
+    "departureDate": "2025-01-30",
+    "path": {
+        "type": "LineString",
+        "coordinates": [
+            [
+                9.182941,
+                48.776261
+            ],
+            [
+                9.182474,
+                48.775559
+            ],
+            // ... more coordinates
+            [
+                8.465909,
+                49.488711
+            ],
+            [
+                8.465364,
+                49.488122
+            ]
+        ]
+    },
+    "lastUpdated": "2025-01-23T12:34:00Z"
+}
+
+```