107 lines
3.4 KiB
Markdown
107 lines
3.4 KiB
Markdown
# 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.
|