Address Geocode and Reverse Geocode APIs
These APIs perform address resolution based on the configured map provider.
Geocode API
Use this API to retrieve longitude and latitude values for a specified address or address fragment. The specified address value is used as a parameter to call the geocode API of the default map provider, along with map provider configuration values. Returns longitude and latitude values of the matching addresses in JSON format.
This API gets the configuration information for the default map provider (for example, the API key, client or service ID, or secret key), and uses those values with the specified latitude and longitude parameter values to construct the URL of the geocode API for the map provider. An HTTP request is then sent to invoke the API, format the request response, and return the formatted result.
API Definition
public static resultObject geocode(String addressKeyword)
The addressKeyword parameter is an address or address fragment used to search for matching addresses and retrieve longitude and latitude values.
The return type is resultObject, which defines the information that is included in the response for this API.
Attributes
|
Name
|
Description
|
|---|---|
|
status_code
|
Status code of the response. For more information, see Geocode API Response Status Codes below.
|
|
status_message
|
Status message of the response.
|
|
Items
|
Array of matching addresses, with latitude and longitude value for each location.
|
|
latitude
|
Latitude value for a matching address.
|
|
longitude
|
Longitude value for a matching address.
|
|
address
|
Full address details for matching addresses. If no detailed addresses are returned from the Map Provider API, returns address fragments instead (word parameter). Used to identify each matching address when multiple addresses are returned.
|
Response
{
"status_code": 0
"status_message": "Success"
"items": [
{
"latitude": "37.6624312",
"longitude": "-121.8746789",
"address": "Pleasanton, California, USA"
},
...
]
}
"status_code": 0
"status_message": "Success"
"items": [
{
"latitude": "37.6624312",
"longitude": "-121.8746789",
"address": "Pleasanton, California, USA"
},
...
]
}
Reverse Geocode API
Use this API to retrieve detailed address information for specified longitude and latitude values. This API gets the configuration information for the default map provider (for example, the API key, client or service ID, or secret key), and uses those values with the specified latitude and longitude parameter values to construct the URL of the reverse geocode API for the map provider. An HTTP request is then sent to invoke the API, format the request response, and return the formatted result.
API Definition
public static resultObject reverseGeocode(String latitude, String longitude)
Response Attributes
The return type is resultObject, which defines the information that is included in the response for this API. This object has the same set of attributes as for the Geocode API, plus additional values. Attributes include the following:
|
Name
|
Description
|
|---|---|
|
status_code
|
Status code of the response. For more information, see Geocode API Response Status Codes below.
|
|
status_message
|
Status message of the response.
|
|
Items
|
Array of matching addresses, each with longitude and latitude and full address details including street, city, state, country, and so on.
|
|
Latitude
|
Latitude of a matching address.
|
|
Longitude
|
Longitude of a matching address.
|
|
Address
|
Detailed address information, formatted as a single-line address
|
|
Country
|
Country of a matching address.
|
|
State
|
Province or state of a matching address.
|
|
City
|
City of a matching address.
|
|
District
|
District of a matching address.
|
|
Route
|
Route for a matching address, for example, US 101.
|
|
Street
|
Street name of a matching address.
|
|
street_number
|
Street number of a matching address.
|
|
country_code
|
Country code of a matching address, for example, US.
|
|
postal_code
|
Postal code of a matching address.
|
Response
{
"status_code": 0
"status_message": "Success"
"items": [
{
"latitude": "37.69414510000001",
"longitude": "-121.9022892",
"address": "5059 Hopyard Rd, Pleasanton, CA, USA, 94588",
"country": "United States",
"state": "California",
"city": "Pleasanton",
"district": null,
"route": "Hopyard Road",
"street": null,
"street_number": "5059",
"country_code": "US",
"postal_code": "94588"
},
...
]
}
"status_code": 0
"status_message": "Success"
"items": [
{
"latitude": "37.69414510000001",
"longitude": "-121.9022892",
"address": "5059 Hopyard Rd, Pleasanton, CA, USA, 94588",
"country": "United States",
"state": "California",
"city": "Pleasanton",
"district": null,
"route": "Hopyard Road",
"street": null,
"street_number": "5059",
"country_code": "US",
"postal_code": "94588"
},
...
]
}
Geocode API Response Status Codes
|
Code
|
Message
|
Description
|
|---|---|---|
|
0
|
Success
|
Successful request. Single matched address returned.
|
|
1
|
Request success but no result return.
|
Successful request. No matched result returned, for example, for example, because invalid address or latitude/longitude values were passed.
|
|
2
|
Request success with multiple results return.
|
Successful request. Multiple matched addresses returned.
|
|
3
|
Invalid request, missing the "addressKeyword" parameter.
Invalid request, missing the "latitude" or "longitude" parameter.
|
Parameter is null, empty, or invalid. Latitude and longitude values must be numbers in String format, with a latitude scope of –90 to 90 and longitude scope of –180 to 180. For example, addressKeyword = "", latitude = "100" causes this error.
|
|
4
|
No default map provider specified in current setting.
|
No default map provider specified in the active system setting.
|
|
5
|
Invalid API Key.
|
Specified API key is invalid.
|
|
6
|
Invalid signature or client id.
|
Specified signature value is invalid for the specified client ID, or the specified client value is invalid.
|
|
7
|
Request over query limit.
|
Request exceeds the query quota.
|
|
8
|
Unable to authenticate the request.
|
Unsuccessful request caused by a map provider server authentication issue.
|
|
9
|
Current map provider is not supported.
|
Current map provider not supported for the Geocode and Reverse Geocode APIs. At this time, only Google and OpenStreetMap are supported.
|
|
101
|
Server Internal Error.
|
Server internal errors occurred on the map provider server.
|
|
102
|
Unknown error.
|
Other unknown errors returned from the map provider server.
|
Address Geocode and Request Geocode API Usage
Import the Class
import com.servicemax.mapproviders.MapProviderManager
Call the APIs
Returns a resultObject object.
result = MapProviderManager.geocode("Mountain View");
result = MapProviderManager.reverseGeocode("37.3893889","-122.0832101");
//get the information from resultObject
res.status_code + " - " + res.status_message + " - " + res.items[0].address
result = MapProviderManager.reverseGeocode("37.3893889","-122.0832101");
//get the information from resultObject
res.status_code + " - " + res.status_message + " - " + res.items[0].address
Convert resultObject to a JSON Object
result.toJsonObject()
Result Example
{
"status_message": "Success",
"status_code": 0,
"items": [
{
"country_code": "us",
"country": "United States of America",
"route": "Church Street",
"address": "Pioneer Park, Church Street, Whisman Station, Mountain View, Santa Clara County, California, 94041, United States of America",
"city": "Mountain View",
for
"latitude": "37.3895365",
"street_number": "",
"state": "California",
"postal_code": "94041",
"longitude": "-122.08317026614"
}
]
}
"status_message": "Success",
"status_code": 0,
"items": [
{
"country_code": "us",
"country": "United States of America",
"route": "Church Street",
"address": "Pioneer Park, Church Street, Whisman Station, Mountain View, Santa Clara County, California, 94041, United States of America",
"city": "Mountain View",
for
"latitude": "37.3895365",
"street_number": "",
"state": "California",
"postal_code": "94041",
"longitude": "-122.08317026614"
}
]
}
Get Nearest Address for Specified Latitude and Longitude
Retrieves the nearest single AddressInfo for a given IGeography latitude-longitude pair.
IGeography geography = new Geography("37.389389", "-122.083210")
AddressInfo address = MapProviderManager.reverseGeocode(geography);
Assert.assertTrue(address.address.contains("828 Church St"))
AddressInfo address = MapProviderManager.reverseGeocode(geography);
Assert.assertTrue(address.address.contains("828 Church St"))
 |
All latitude and longitude input values must be in the WGS84 coordinate system. Output values are also in this format. Each map provider API has different response attributes, which are converted to a consistent object with a single set of attributes, for example, resultObject.
|