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. Once you have your key, you can make a GET request to the endpoint.

Endpoint: `foomatic.ca/route/request_route` test changes

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:

{
  "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:

{
  "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:

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

README.md