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. |
The Geocode endpoint returns information regarding an address. This broadly includes coordinates, formatted address, accuracy information and much more.
OK
Bad Request
Unauthorized
Not Found.
Internal Server Error
Gateway Timeout Error - All third party geocoders are unreachable. Try again later
{- "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
}
}
{- "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
}, - "entranceCoordinates": {
- "points": [
- {
- "lat": 50.5861424,
- "lng": 6.6071824,
- "confidenceRadiusMeters": 5.91896586306578,
- "coordinateId": "76da20ee-2d68-11ef-bb8c-e9eddcbf2fa6"
}, - {
- "lat": 50.58615,
- "lng": "7.60743335,",
- "confidenceRadiusMeters": "-1.0,",
- "coordinateId": "76da0168-2d68-11ef-bb8c-e9eddcbf2fa6"
}
]
}, - "parkingCoordinates": {
- "points": [ ]
}, - "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"
}
The Geocode Bulk endpoint returns information regarding all the incoming addresses. This broadly includes coordinates, formatted address, accuracy information and much more.
object The Addresses object contains the list of addresses to be normalized and geocoded. Note: The list size cannot exceed 100 addresses. |
OK
Bad Request
Unauthorized
Not Found
Internal Server Error
{- "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
}
}
}
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": {
- "id1": {
- "rawAddressId": 12345,
- "coordinates": {
- "lat": 44.4064,
- "lng": 8.93751
}, - "streetCoordinates": null,
- "entranceCoordinates": {
- "points": [
- {
- "lat": 50.5861424,
- "lng": 6.6071824,
- "confidenceRadiusMeters": 5.91896586306578,
- "coordinateId": "76da20ee-2d68-11ef-bb8c-e9eddcbf2fa6"
}, - {
- "lat": 50.58615,
- "lng": "7.60743335,",
- "confidenceRadiusMeters": "-1.0,",
- "coordinateId": "76da0168-2d68-11ef-bb8c-e9eddcbf2fa6"
}
]
}, - "parkingCoordinates": {
- "points": [ ]
}, - "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
}, - "streetCoordinates": null,
- "entranceCoordinates": {
- "points": [ ]
}, - "parkingCoordinates": {
- "points": [ ]
}, - "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"
}
}
}
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.
OK
Bad Request
Unauthorized
Not Found: Raw Address Entity not found
Internal Server Error
{- "rawAddressId": 74817480,
- "coordinates": {
- "lat": 44.86076,
- "lng": 8.07147
}, - "userId": "f19a2574-2769-11ed-a261-0242ac120002",
- "userComment": "Yellow building"
}
{- "id": 20,
- "rawAddressId": 74817480,
- "geocoderType": "MANUAL",
- "correctedAt": "2022-04-19T13:13:24.173112Z",
- "data": {
- "street": "Borgata San Giacomo",
- "number": "4b",
- "postalCode": 14015,
- "city": "San Damiano d'Asti",
- "subLocality": null,
- "country": "IT",
- "formattedAddress": "Borgata San Giacomo, 4b, 14015 San Damiano d'Asti AT, Italia",
- "coordinates": {
- "lat": 44.86075,
- "lng": 8.07145
}
}, - "previousCoordinates": {
- "lat": 44.86076,
- "lng": 8.07147
}, - "originalCoordinates": {
- "lat": 44.86076,
- "lng": 8.07147
}, - "accuracy": {
- "score": "ADDRESS_POINT",
- "houseNumberFallback": null,
- "postalCodeChangeValid": null,
- "possibleFalsePositive": null
}, - "status": "PENDING_REVIEW",
- "userId": "f19a2574-2769-11ed-a261-0242ac120002",
- "userComment": "Yellow building"
}