Geocode

Geocode is a collection of geocode related endpoints.

This includes endpoints that allow to normalise and geocode addresses to get highly accurate results that are also validated and improved by real drivers every day.

The level of quality of geocoding is defined by the accuracy level returned to the accuracy.level field.

The following are the different accuracy levels currently supported:

Accuracy Level Score Description
ADDRESS_POINT 100 Address is accurate to the house door or rooftop
MANUAL_GEOCODING 95 The address was manually geocoded by a Bettermile employee using multiple sources of information.
STREET_COORDINATES 90 The address was translated to street coordinates derived from the geocoder result.
INTERPOLATED_POINT 80 Location was calculated using interpolation between two known points.
STREET_CENTROID 50 Location was geocoded to the center of the street.
POSTAL_CENTROID 30 Location was geocoded to the center of the postal code.
LOCALITY_CENTROID 10 Location was geocoded to the center of the locality.

Geocode

The Geocode endpoint returns information regarding an address. This broadly includes coordinates, formatted address, accuracy information and much more.

SecuritybasicAuth
Request
query Parameters
debug
boolean

to get naId and gaId specify debug parameter like this ?debug. The value can be true or false

Request Body schema: application/json
object

A specified period of time in which is planned a delivery to take place.

object

Address Object to be normalized and geocoded.

Responses
200

OK

400

Bad Request

401

Unauthorized

404

Not Found.

500

Internal Server Error

504

Gateway Timeout Error - All third party geocoders are unreachable. Try again later

post/api/v1/geocode
Request samples
application/json
{
  • "timeframe": {
    },
  • "address": {
    }
}
Response samples
application/json
{
  • "rawAddressId": 12345,
  • "timeframe": {
    },
  • "coordinates": {
    },
  • "streetCoordinates": {
    },
  • "entranceCoordinates": {
    },
  • "parkingCoordinates": {
    },
  • "formatted": "Otto-Weidt-Platz 8, 10557 Berlin, Germany",
  • "street": "Otto-Weidt-Platz",
  • "number": 8,
  • "postalCode": 10557,
  • "locality": "Berlin",
  • "countryCode": "DE",
  • "accuracy": {
    },
  • "zoneId": "Europe/Berlin"
}

Geocode Bulk

The Geocode Bulk endpoint returns information regarding all the incoming addresses. This broadly includes coordinates, formatted address, accuracy information and much more.

SecuritybasicAuth
Request
Request Body schema: application/json
object

The Addresses object contains the list of addresses to be normalized and geocoded. Note: The list size cannot exceed 100 addresses.

Responses
200

OK

400

Bad Request

401

Unauthorized

404

Not Found

500

Internal Server Error

post/api/v1/geocode/bulk
Request samples
application/json
{
  • "addresses": {
    }
}
Response samples
application/json

The property "results" has one key/value pair per geocoded address. The key is always id[counter] while the value is the geocoded address response.

{
  • "results": {
    }
}

Geocode Correction

The Geocode Correction endpoint allows to send a geocoding correction to a specific single address.

Corrections could be location data like coordinates, or the correct spelling of the street name, the correct house number or postal code.

The correction will undergo several filters before it is approved but once it's approved, any next request to the same address will be served with the corrected version.

SecuritybasicAuth
Request
Request Body schema: application/json
rawAddressId
required
number <int64>

The id of the address the correction is for.

required
object

Object that contains the latitude and longitude of the geocoded address. BetterPlaces uses the Web Mercator Projection standard to represent latitudes and longitudes.

userId
required
string

User identification.

userComment
string

User observations.

Responses
200

OK

400

Bad Request

401

Unauthorized

404

Not Found: Raw Address Entity not found

500

Internal Server Error

post/api/v1/geocode/correction
Request samples
application/json
{
  • "rawAddressId": 74817480,
  • "coordinates": {
    },
  • "userId": "f19a2574-2769-11ed-a261-0242ac120002",
  • "userComment": "Yellow building"
}
Response samples
application/json
{
  • "id": 20,
  • "rawAddressId": 74817480,
  • "geocoderType": "MANUAL",
  • "correctedAt": "2022-04-19T13:13:24.173112Z",
  • "data": {
    },
  • "previousCoordinates": {
    },
  • "originalCoordinates": {
    },
  • "accuracy": {
    },
  • "status": "PENDING_REVIEW",
  • "userId": "f19a2574-2769-11ed-a261-0242ac120002",
  • "userComment": "Yellow building"
}