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

```bash
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"
  }
}'
```

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](https://benomad.com/dev/doc/bemap-api/api/routing/routing.md) lists every option and what it adds.

Response captured from production, long arrays and strings shortened:

```json
{
  "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}"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

## Conventions to know

- **BeMap ignores a field it does not know.** A misspelt field name answers `200` and changes nothing. Check every name against the reference, or give your coding assistant the [BeMap MCP server](https://benomad.com/dev/doc/bemap-api/products/mcp.md), which knows them all.
- **Lists are JSON arrays.** When a field takes several values, such as `options` or `routingCriterias`, send an array: a comma-separated string answers `400`.
- **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.