Your first request#
This request computes a route between two points in Paris and Brussels. It is a real call: the body below was sent to the production service, and the response under it is what came back.
curl -X POST 'https://bemap.benomad.com/bgis/service/routing/1.0' \
-u 'YOUR_ACCOUNT:YOUR_API_KEY' \
--fail-with-body \
-H 'Content-Type: application/json' \
-d '{
"routingMode": "MODE_VIAS",
"outputLanguage": "fr",
"destinations": [
{
"coordinateSat": {
"lon": 2.32158,
"lat": 48.86533
}
},
{
"coordinateSat": {
"lon": 4.35655,
"lat": 50.8447
}
}
],
"routingCriterias": [
"FASTEST"
],
"options": [
"POLYLINE",
"EVENT",
"EVT_LENGTH",
"EVT_DURATION"
],
"routingVehicleProfile": {
"transportMode": "CAR"
}
}'const response = await fetch('https://bemap.benomad.com/bgis/service/routing/1.0', {
method: 'POST',
headers: {
Authorization: 'Basic ' + btoa('YOUR_ACCOUNT:YOUR_API_KEY'),
'Content-Type': 'application/json',
},
body: JSON.stringify({
"routingMode": "MODE_VIAS",
"outputLanguage": "fr",
"destinations": [
{
"coordinateSat": {
"lon": 2.32158,
"lat": 48.86533
}
},
{
"coordinateSat": {
"lon": 4.35655,
"lat": 50.8447
}
}
],
"routingCriterias": [
"FASTEST"
],
"options": [
"POLYLINE",
"EVENT",
"EVT_LENGTH",
"EVT_DURATION"
],
"routingVehicleProfile": {
"transportMode": "CAR"
}
}),
redirect: 'manual', // a missing credential answers 302: never follow it
});
if (response.type === 'opaqueredirect' || (response.status >= 300 && response.status < 400)) throw new Error('BeMap redirected to its login page: no credentials reached it');
if (!response.ok) throw new Error(`BeMap answered ${response.status}: ${await response.text()}`);
const data = await response.json();import requests
response = requests.post(
"https://bemap.benomad.com/bgis/service/routing/1.0",
auth=("YOUR_ACCOUNT", "YOUR_API_KEY"),
json={
"routingMode": "MODE_VIAS",
"outputLanguage": "fr",
"destinations": [
{
"coordinateSat": {
"lon": 2.32158,
"lat": 48.86533,
},
},
{
"coordinateSat": {
"lon": 4.35655,
"lat": 50.8447,
},
},
],
"routingCriterias": ["FASTEST"],
"options": ["POLYLINE", "EVENT", "EVT_LENGTH", "EVT_DURATION"],
"routingVehicleProfile": {
"transportMode": "CAR",
},
},
allow_redirects=False, # a missing credential answers 302: never follow it
)
if response.is_redirect:
raise RuntimeError("BeMap redirected to its login page: no credentials reached it")
if response.status_code != 200:
raise RuntimeError(f"BeMap answered {response.status_code}: {response.text}")
data = response.json()import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
String auth = Base64.getEncoder().encodeToString("YOUR_ACCOUNT:YOUR_API_KEY".getBytes(StandardCharsets.UTF_8));
String body = """
{
"routingMode": "MODE_VIAS",
"outputLanguage": "fr",
"destinations": [
{
"coordinateSat": {
"lon": 2.32158,
"lat": 48.86533
}
},
{
"coordinateSat": {
"lon": 4.35655,
"lat": 50.8447
}
}
],
"routingCriterias": [
"FASTEST"
],
"options": [
"POLYLINE",
"EVENT",
"EVT_LENGTH",
"EVT_DURATION"
],
"routingVehicleProfile": {
"transportMode": "CAR"
}
}
""";
HttpRequest request = HttpRequest.newBuilder(URI.create("https://bemap.benomad.com/bgis/service/routing/1.0"))
.header("Authorization", "Basic " + auth)
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString(body))
.build();
// HttpClient never follows redirects by default: a 302 means a missing credential.
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() / 100 == 3) throw new IllegalStateException("BeMap redirected to its login page: no credentials reached it");
if (response.statusCode() != 200) throw new IllegalStateException("BeMap answered " + response.statusCode() + ": " + response.body());
String json = response.body();<?php
$body = <<<'JSON'
{
"routingMode": "MODE_VIAS",
"outputLanguage": "fr",
"destinations": [
{
"coordinateSat": {
"lon": 2.32158,
"lat": 48.86533
}
},
{
"coordinateSat": {
"lon": 4.35655,
"lat": 50.8447
}
}
],
"routingCriterias": [
"FASTEST"
],
"options": [
"POLYLINE",
"EVENT",
"EVT_LENGTH",
"EVT_DURATION"
],
"routingVehicleProfile": {
"transportMode": "CAR"
}
}
JSON;
$ch = curl_init('https://bemap.benomad.com/bgis/service/routing/1.0');
curl_setopt_array($ch, [
CURLOPT_USERPWD => 'YOUR_ACCOUNT:YOUR_API_KEY',
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => $body,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false, // a missing credential answers 302: never follow it
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status >= 300 && $status < 400) throw new RuntimeException('BeMap redirected to its login page: no credentials reached it');
if ($status !== 200) throw new RuntimeException("BeMap answered $status: $response");
$data = json_decode($response, true);using System.Net;
using System.Net.Http.Headers;
using System.Text;
// AllowAutoRedirect = false: a missing credential answers 302, never follow it.
var client = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false });
var token = Convert.ToBase64String(Encoding.UTF8.GetBytes("YOUR_ACCOUNT:YOUR_API_KEY"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", token);
var body = """
{
"routingMode": "MODE_VIAS",
"outputLanguage": "fr",
"destinations": [
{
"coordinateSat": {
"lon": 2.32158,
"lat": 48.86533
}
},
{
"coordinateSat": {
"lon": 4.35655,
"lat": 50.8447
}
}
],
"routingCriterias": [
"FASTEST"
],
"options": [
"POLYLINE",
"EVENT",
"EVT_LENGTH",
"EVT_DURATION"
],
"routingVehicleProfile": {
"transportMode": "CAR"
}
}
""";
var response = await client.SendAsync(new HttpRequestMessage(HttpMethod.Post, "https://bemap.benomad.com/bgis/service/routing/1.0")
{
Content = new StringContent(body, Encoding.UTF8, "application/json"),
});
if ((int)response.StatusCode / 100 == 3) throw new HttpRequestException("BeMap redirected to its login page: no credentials reached it");
if (response.StatusCode != HttpStatusCode.OK) throw new HttpRequestException($"BeMap answered {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");
var json = await response.Content.ReadAsStringAsync();Replace YOUR_ACCOUNT and YOUR_API_KEY with your own and run it. Every operation page has the same samples, and a Try it button that sends the request from your browser with your credentials.
Reading the answer#
A successful call answers 200 with a JSON body. What the body contains depends on the request: a route without options returns its totals, and each option adds a part of the answer: the geometry with POLYLINE, the events along the road with EVENT (at the least, the country of each segment), the route sheet and its turn-by-turn instructions with ROUTESHEET. The routing reference lists every option and what it adds.
{
"usedDestinations": [
{
"inputOrder": 0,
"used": true,
"usedOrder": 0,
"matchedCoordinateGps": {
"lon": 2.320602551430303,
"lat": 48.86560827817406
},
"confidenceValue": 0.011525919841882743,
"distanceFromRequest": 77.99,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 1,
"used": true,
"usedOrder": 1,
"matchedCoordinateGps": {
"lon": 4.356551847665557,
"lat": 50.84469883685485
},
"confidenceValue": 0.10126977925376049,
"distanceFromRequest": 0.13,
"polylineIndex": -1,
"duration": 12255,
"length": 308429
}
],
"routingRoutes": [
{
"length": 308429,
"duration": 12255,
"totalDuration": 12255,
"trafficDelay": 0,
"departureTime": 0,
"arrivalTime": 0,
"averageSpeed": 90.60338,
"maximumSpeed": 0,
"startUTurnThreshold": 3000,
"boundingBox": {
"minLon": 2.30156,
"minLat": 48.86560827817406,
"maxLon": 4.356551847665557,
"maxLat": 50.84507
},
"startStopInfo": {
"start": {
"lon": 2.3206,
"lat": 48.86561
},
"stop": {
"lon": 4.35655,
"lat": 50.8447
},
"distanceFirstMatched": 0.19,
"distanceLastMatched": 0.13,
"interDests": null
},
"polyline": [
{
"lon": 2.320602551430303,
"lat": 48.86560827817406
},
{
"lon": 2.32063,
"lat": 48.86565
}
],
"events": [
{
"type": "SEGMENT",
"distanceUnit": "meters",
"timeUnit": "seconds",
"markers": [
{
"distance": 0,
"time": 0,
"percent": 0,
"entries": [
{
"type": "String",
"name": "countryCode",
"jsonObject": "{\"type\":\"String\",\"value\":\"FRA\"}"
},
{
"type": "long",
"name": "length",
"jsonObject": "{\"type\":\"long\",\"value\":6}"
},
{
"type": "double",
"name": "duration",
"jsonObject": "{\"type\":\"double\",\"value\":0.74609375}"
}
]
},
{
"distance": 6,
"time": 1,
"percent": 0.0019453423640448855,
"entries": [
{
"type": "String",
"name": "countryCode",
"jsonObject": "{\"type\":\"String\",\"value\":\"FRA\"}"
},
{
"type": "long",
"name": "length",
"jsonObject": "{\"type\":\"long\",\"value\":80}"
},
{
"type": "double",
"name": "duration",
"jsonObject": "{\"type\":\"double\",\"value\":15.95703125}"
}
]
}
]
}
]
}
]
}Long arrays and strings are shortened on this page.
Conventions to know#
- BeMap ignores a field it does not know. A misspelt field name answers
200and changes nothing. Check every name against the reference, or give your coding assistant the BeMap MCP server, which knows them all. - Lists are JSON arrays. When a field takes several values, such as
optionsorroutingCriterias, send an array: a comma-separated string answers400. - Dates and times do not all take one form. A date you send takes the form its description in the reference gives: most take a count of milliseconds since 1 January 1970, UTC, or ISO date and time text. A date you receive is most often a count of milliseconds, but the reference does not describe every one. The route on this page gives its departure and arrival in seconds, counted in the local time of the start point, so a start in Paris in summer reads two hours ahead of UTC, and both are zero when the request sets no departure time. Trace route gives them in seconds too, without that shift. Traffic dates come as milliseconds, although the reference types them as date and time text. Check the form in a real answer before your code relies on it.