Vai al contenuto
Floweet
Accesso professionisti

Geocoding and routes

Find the coordinates of an address (French national address base, then OpenStreetMap) and compute a road route of 2 to 25 points, distance and duration.

api.floweet.com/v1 · Contract 1.0.0-beta.1 · Beta

This documentation is written in English and French; it is shown to you in English.

Sections · Geocoding and routes
On this page
  1. Good to know
  2. Source and reuse
  3. The Geocode object
  4. The Route object
  5. Geocode an address (France: national address base; other markets: OpenStreetMap)
  6. Road route (car) through 2 to 25 points

Two tools to put your clients on the map: geocoding, which finds the coordinates of an address, and road routing, which gives the distance, duration and shape of a route through 2 to 25 points.

Good to know

  • Geocoding: the French national address base (Base Adresse Nationale) for France, then OpenStreetMap for other markets; without country, France first. Five results at most, most likely first.
  • Routes: car profile. geometry is the full shape, point by point: expect several hundred KB for a long route. Only ask for routes whose shape you display.
  • These services are shared: 30 calls a minute per organization, on top of the general limit (see rate limits). Cache addresses you have already geocoded.
  • An upstream outage answers 502 geocode_unavailable or 502 route_unavailable: retry with a growing delay.

Source and reuse

Addresses: Base Adresse Nationale (Licence Ouverte 2.0); elsewhere, and for routes: © OpenStreetMap contributors (ODbL), to be credited.

The Geocode object

FieldTypeDescription
resultsalways presentobject[]5 at most.
results[].labelalways presentstring
results[].latalways presentnumber
results[].lngalways presentnumber
Geocode
{
  "results": [
    {
      "label": "12 Rue de la République 69002 Lyon",
      "lng": 4.835769,
      "lat": 45.76511
    },
    {
      "label": "Rue de la République 69001 Lyon",
      "lng": 4.836016,
      "lat": 45.76637
    },
    {
      "label": "Place de la République 69002 Lyon",
      "lng": 4.835689,
      "lat": 45.760722
    }
  ]
}

The Route object

FieldTypeDescription
distanceKmalways presentnumber
durationMinalways presentnumber
legsalways presentobject[]
legs[].distanceKmalways presentnumber
legs[].durationMinalways presentnumber
geometryalways presentobject[]
geometry[].latalways presentnumber
geometry[].lngalways presentnumber
Route
{
  "distanceKm": 465.9,
  "durationMin": 298,
  "legs": [
    {
      "distanceKm": 465.9,
      "durationMin": 298
    }
  ],
  "geometry": [
    {
      "lat": 48.857243,
      "lng": 2.352316
    },
    {
      "lat": 48.857254,
      "lng": 2.352327
    },
    {
      "lat": 48.857283,
      "lng": 2.352354
    },
    {
      "lat": 45.763837,
      "lng": 4.835663
    }
  ]
}

Geocode an address (France: national address base; other markets: OpenStreetMap)

GET/v1/geocodeScope geo:read

Parameters

FieldInTypeDescription
qrequiredquerystring1 to 200 characters
countryoptionalquery"fr" | "de" | "es" | "it" | "pt"Absent: France (BAN) then every market.

Response 200

OK — A Geocode object

Errors

HTTPMeaning
400Invalid request
401Missing, invalid or revoked API key
403Forbidden (scope, plan or account status)
404Resource not found
429Too many requests
500Internal error
502Upstream service error
Request
curl "https://api.floweet.com/v1/geocode?q=12%20rue%20de%20la%20R%C3%A9publique%2C%20Lyon" \
  -H "Authorization: Bearer $FLOWEET_API_KEY"
Response 200
{
  "results": [
    {
      "label": "12 Rue de la République 69002 Lyon",
      "lng": 4.835769,
      "lat": 45.76511
    },
    {
      "label": "Rue de la République 69001 Lyon",
      "lng": 4.836016,
      "lat": 45.76637
    },
    {
      "label": "Place de la République 69002 Lyon",
      "lng": 4.835689,
      "lat": 45.760722
    }
  ]
}

Road route (car) through 2 to 25 points

POST/v1/routesScope geo:read

Parameters

FieldInTypeDescription
Idempotency-Keyoptionalheaderstringat most 255 charactersUnique key for this request (a new UUID v4, kept for its retries): the first response is replayed for 24 hours.

Request body RouteInput

FieldTypeDescription
pointsrequiredobject[]2 to 25 items
points[].latrequirednumberfrom -90 to 90
points[].lngrequirednumberfrom -180 to 180

Response 200

OK — A Route object

Errors

HTTPMeaning
400Invalid request
401Missing, invalid or revoked API key
403Forbidden (scope, plan or account status)
404Resource not found
429Too many requests
500Internal error
502Upstream service error
Request
curl -X POST "https://api.floweet.com/v1/routes" \
  -H "Authorization: Bearer $FLOWEET_API_KEY" \
  -H "Idempotency-Key: 6f1c2b0e-8d4a-4f7e-9a51-3c2d1e0f9b87" \
  -H "Content-Type: application/json" \
  -d '{
  "points": [
    {
      "lat": 48.8566,
      "lng": 2.3522
    },
    {
      "lat": 45.764,
      "lng": 4.8357
    }
  ]
}'
Response 200
{
  "distanceKm": 465.9,
  "durationMin": 298,
  "legs": [
    {
      "distanceKm": 465.9,
      "durationMin": 298
    }
  ],
  "geometry": [
    {
      "lat": 48.857243,
      "lng": 2.352316
    },
    {
      "lat": 48.857254,
      "lng": 2.352327
    },
    {
      "lat": 48.857283,
      "lng": 2.352354
    },
    {
      "lat": 45.763837,
      "lng": 4.835663
    }
  ]
}