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

400

Bad Request

401

Unauthorized

404

Not Found: indicates that the address couldn't be geocoded due to bad address information.

500

Internal Server Error

post/api/v1/geocode

Request samples

Payload
curl
Java
Python
JavaScript

application/json

{"timeframe": {"earliest": "09:00:00",
"latest": "10:00:00",
"zoneId": "Europe/Berlin"
},
"address": {"street": "Otto-Weidt-Platz",
"number": 9,
"postalCode": 10557,
"locality": null,
"province": null,
"countryCode": "DE",
"w3w": null
}
}

Response samples

application/json

{"rawAddressId": 12345,
"timeframe": {"earliest": "09:00:00",
"latest": "10:00:00",
"zoneId": "Europe/Berlin"
},
"coordinates": {"lat": 52.53294,
"lng": 13.36718
},
"streetCoordinates": {"lat": 51.1234,
"lng": 12.7478
},
"formatted": "Otto-Weidt-Platz 8, 10557 Berlin, Germany",
"street": "Otto-Weidt-Platz",
"number": 8,
"postalCode": 10557,
"locality": "Berlin",
"countryCode": "DE",
"accuracy": {"houseNumberFallback": null,
"houseNumberChanged": false,
"postalCodeChanged": false,
"postalCodeChangeValid": null,
"score": 100,
"level": "ADDRESS_POINT"
},
"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

Addresses Object to be normalized and geocoded.

Responses

200

400

Bad Request

401

Unauthorized

500

Internal Server Error

post/api/v1/geocode/bulk

Request samples

Payload
curl
Java
Python
JavaScript

application/json

{"addresses": {"id1": {"street": "Viaaaa 20 Settembre, 196/R 16121 Genova",
"number": null,
"postalCode": null,
"locality": null,
"countryCode": "IT",
"province": "GE",
"w3w": null
},
"id2": {"street": "lichtenberger str 41",
"number": null,
"postalCode": null,
"locality": "Berlin",
"countryCode": "DE",
"province": "Berlin",
"w3w": null
}
}
}

Response samples

application/json

{"results": {"id1": {"rawAddressId": 12345,
"coordinates": {"lat": 44.4064,
"lng": 8.93751
},
"formatted": "Via XX Settembre, 196, 16121 Genova GE, Italy",
"street": "Via XX Settembre",
"number": 196,
"postalCode": 16121,
"locality": "Genova",
"countryCode": "IT",
"accuracy": {"houseNumberFallback": null,
"houseNumberChanged": true,
"postalCodeChanged": false,
"postalCodeChangeValid": null,
"score": null,
"level": null
},
"zoneId": "Europe/Rome"
},
"id2": {"rawAddressId": 12345,
"coordinates": {"lat": 52.51389,
"lng": 13.42595
},
"formatted": "Lichtenberger Str. 41, 10179 Berlin, Germany",
"street": "Lichtenberger Straße",
"number": 41,
"postalCode": 10179,
"locality": "Berlin",
"countryCode": "DE",
"accuracy": {"houseNumberFallback": null,
"houseNumberChanged": true,
"postalCodeChanged": true,
"postalCodeChangeValid": null,
"score": 100,
"level": "ADDRESS_POINT"
},
"zoneId": "Europe/Berlin"
}
}
}

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

400

Bad Request

401

Unauthorized

500

Internal Server Error

post/api/v1/geocode/correction

Request samples

Payload
curl
Java
Python
JavaScript

application/json

{"rawAddressId": 74817480,
"coordinates": {"lat": 44.86076,
"lng": 8.07147
},
"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",
"accuracy": "ADDRESS_POINT",
"status": "PENDING_REVIEW",
"userId": "f19a2574-2769-11ed-a261-0242ac120002",
"userComment": "Yellow building",
"data": {"street": "Borgata San Giacomo",
"number": "4b",
"postalCode": 14015,
"city": "San Damiano d'Asti",
"subLocality": null,
"formattedAddress": "Borgata San Giacomo, 4b, 14015 San Damiano d'Asti AT, Italia",
"coordinates": {"lat": 44.86076,
"lng": 8.07147
}
}
}