From 89ee6e55660b92c88f6ed57694ec0cbc35deaf6c Mon Sep 17 00:00:00 2001 From: opoolad1 Date: Thu, 19 Mar 2026 12:41:09 -0500 Subject: [PATCH] Added intro and description --- .README.md.un~ | Bin 0 -> 7549 bytes README.md | 8 ++++ README.md~ | 106 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 114 insertions(+) create mode 100644 .README.md.un~ create mode 100644 README.md~ diff --git a/.README.md.un~ b/.README.md.un~ new file mode 100644 index 0000000000000000000000000000000000000000..40636b9e4ee25b73aaae7627e8cbf0acaeeed97b GIT binary patch literal 7549 zcmeHM&1(}u6yL`B?WuUMc<@0FLa2pmdn}?9KQ7io^{7mCC&}pUOqiKXObCaz>FHG_v2viV^tt~4^*mVwPluDQt z;ZXxxrIv$gSdoYov?&QnqM-`5&Y{AMorV^NBsCUTY!p<}IBo-%p-LLe7)WJ9^GJlu zvPz5^b(d4=f4Xzs4omC(rF0H7dNf{$(3|uyaRx&|5i(NHibsE}K z<7=I*FdboQv7+Xo5i==y)N#ZNoNi-@rt2BX<#Vnujjdb;=ZKI=Y@faY9mK2~YZwdc z%0PE;{6>Row1wz~L`acfznIC|osSSQ)SMa2j5K`>7*^%BJ%cdqL%oYShPoe>gi^18 z*qHkTAkHDRmO}OIbTmUFF{>uBlvs;_-iaKx~|N@8Af6Z-=m9f?^kH4b@>d zH3druaZ~Wt{HjCDBZMWKP?eq8b5J1WJu$2l5&Ps28|xrO!Ll1wpmqbvVL6T#!jf_b zv>*eJN>QE{YN7jH0O;K^tQ2R!rF_VF0Iy+(d6>xFjVpX6i1wg5DPZ!R*kno}b0n+V z^(wwMeR~Mg%{)w0;Q(rknup0pnXgBX`Bku(4!u`4oAv|KtvpP7u_xL);C_){D)x*c zzGuwVB#Iis+6%2)6h*JdP)v5@g#o0WD0J+6(cWIKDxK zg5%_c0i+*}caD(Rq5t1K)7h=Tak||5ducX;_hA{^J-a=mj{jmK@ zuNnR1R%H7K-TG!M_mhZ+k{C|;+i{;0+8_S3PcSc5RB5_{mcA+44 j-XnuN_e1ROj@YHneYc-y`~}bKb|d!C|E8N?{rKb$D*J!{ literal 0 HcmV?d00001 diff --git a/README.md b/README.md index 77230bd..1fa1c92 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,14 @@ # Foomatic Routing and Distance API ## Overview + + +Foomatic is a route planning company that provides services at businesses that need to optimize complex, multi-week long trips for traveling salespeople, or product delivery routes in both big cities and rural areas. +This is the API Reference for Foomatic. This guide provides detailed information on the API you can use to interact with the Foomatic Platform. + + +To make Foomatic's route optimization one of the best, we must have a fully optimized API. This API allows our routing algorithms and delivery people to identify the best possible planned route. By having an API we can ensure that our clients delivery experiences minimal delays and increases driver safety. + 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. diff --git a/README.md~ b/README.md~ new file mode 100644 index 0000000..4369af4 --- /dev/null +++ b/README.md~ @@ -0,0 +1,106 @@ +# Foomatic Routing and Distance API + +## Overview + +This is the API Reference for Foomatic. This guide provides detailed information on the API you can use to interact with the Foomatic Platform. + +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.