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