Upload files to "/"

2026-03-19 17:31:54 +01:00
commit 72b57c9ee3
1 changed files with 103 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,103 @@
+# Foomatic Routing and Distance API
+
+## Overview
+Foomatic utilizes a REST API to calculate the shortest road distance between two sets of geographic coordinates. You can recieve a link to foomatic page with route details, or a simple kilometer calculation.
+
+To use this API, you must first request an API key here: [Get your Key](https://foomatic.ca/requestkey). Once you have your key, you can make a `GET` request to the endpoint.
+
+**Endpoint:**
+`foomatic.ca/route/request_route`
+
+---
+
+## Request Parameters
+
+Add the following parameters to your URL string:
+
+* **`start_lat`** (float): Starting latitude in decimal degrees.
+* **`start_long`** (float): Starting longitude in decimal degrees.
+* **`end_lat`** (float): End latitude in decimal degrees.
+* **`end_long`** (float): End longitude in decimal degrees.
+* **`api_key`** (string): Your super secret key.
+* **`map_link`** (boolean):**Optional** If included (ie., `&map_link=true`), the API will return a URL link to the Foomatic route visualizer page. If omitted, the API defaults to returning the raw total distance.
+
+---
+
+## Example Requests & Responses
+
+### 1. Requesting a Map Route URL
+Use this request when you want to redirect a user to a visual map of their route. Note the addition of `&map_link=true` at the end of the URL.
+
+**Sample Request:**
+```
+foomatic.ca/route/request_route?start_lat=44.6488&start_long=-63.5752&end_lat=46.0878&end_long=-64.7782&api_key=YOUR_SUPER_SECRET_KEY&map_link=true
+```
+
+**Sample Response:**
+```json
+{
+  "status": "success",
+  "data": {
+    "route_url": "[https://foomatic.ca/app/view-map?origin=44.6488,-63.5752&dest=46.0878,-64.7782](https://foomatic.ca/app/view-map?origin=44.6488,-63.5752&dest=46.0878,-64.7782)",
+    "description": "Click this link to view your route on the map."
+  }
+}
+```
+
+### 2. Requesting Raw Distance Data
+Use this standard request when you only need the mathematical distance to use within your own application.
+
+**Sample Request:**
+```
+foomatic.ca/route/request_route?start_lat=44.6488&start_long=-63.5752&end_lat=46.0878&end_long=-64.7782&api_key=YOUR_SUPER_SECRET_KEY
+```
+
+**Sample Response:**
+```json
+{
+  "status": "success",
+  "message": "Distance calculated successfully.",
+  "data": {
+    "distance": 186.24,
+    "unit": "km",
+    "origin": {
+      "latitude": 44.6488,
+      "longitude": -63.5752
+    },
+    "destination": {
+      "latitude": 46.0878,
+      "longitude": -64.7782
+    }
+  }
+}
+```
+
+### 3. **Sample Error repsonse:**
+```json
+{
+  "status": "error",
+  "message": "Missing coordinate parameter",
+  "error_code": "MISSING_PARAMETER",
+  "requirements":{
+    "origin": [
+      "start_lat",
+      "start_long"
+    ],
+    "destination": [
+      "end_lat",
+      "end_long"
+    ],
+    "API_key":[
+        "SUPER_SECRET_KEY"
+    ]
+  }
+}
+```
+### 4. **Status/Error codes:**
+* **"success":** no errors indicated.
+* **"error":** error indicated look at error code for description.
+* **"MISSING_PARAMETER":** One of the 4 required parameters is missing or invalid. Verify coordinates and re-request.
+* **"INVALID_AUTH":** Your super secret key is invalid or not authorized, verify correct key or request new.
+
+### 5. Usage limits
+Free accounts may use this service 5 times a day. If API key is registered to corporate or paid-access usage is unlimited, time-gated 480 seconds between requests.