Geocode GET Request

The GET request enables you to submit an input address and matching and/or geocoding preferences to the Geocode service and receive a response that provides the candidates object which contains the associated latitude/longitude coordinates and other matching and location information about each candidate. The preference options for a GET request are a subset of the total available with the POST request.

Base URI

http://<server>:<port>/rest/GlobalGeocode/geocode[.content type]

where:

[.content type] indicates that the specified content type will be used by default. Optional.

json: Default content type is JSON, unless superseded by HTTP content negotiation
xml: Default content type is XML, unless superseded by HTTP content negotiation

[query parameters] are described in the following section. Each key/value pair entered in the request is separated by an ampersand.

Query Parameters

The following table defines the GET query parameters for the Geocode service. For information on the response, see GeocodeServiceResponse Object.

Parameter	Type	Description
placeName	String	Building name, place name, Point of Interest (POI), company or firm name associated with the input address. Optional. For example: Pitney Bowes 4750 Walnut St. Boulder, CO 80301
mainAddress	String	Single Line input—If no other field is populated, then the mainAddress entry will be treated as a single line input and can be a collection of address field elements. The input order of the address fields should reflect the normal address formatting for your country. Optional. For example: 4750 Walnut St., Boulder CO, 80301 Street Address—If the address fields (placeName, lastLine, postalCode, etc.) are provided separately, then the content of this field will be treated as the street address part and can include company name, house number, building names and street names. Optional. Street Intersection Input—To enter an intersection, specify the two street names separated by a double ampersand (&&).
lastLine	String	The last line of the address. Optional.
areaName1	String	Specifies the largest geographic area, typically a state or province. Optional.
areaName2	String	Specifies the secondary geographic area, typically a county or district. Optional.
areaName3	String	Specifies a city or town name. Optional.
areaName4	String	Specifies a city subdivision or locality. Optional.
postalCode	String	The postal code in the appropriate format for the country. Optional.
country	String	ISO 3166-1 alpha-3 country code. Required. For country codes, see Country Reference Listing and ISO 3166-1 Country Codes.
matchMode	String	Match modes determine the leniency used to make a match between the input address and the reference data. Select a match mode based on the quality of your input and your desired output. The following match modes are available: Exact Requires a very tight match. This restrictive mode generates the fewest match candidates, which decreases the processing time. When using this mode, ensure that your input is very clean; free of misspellings and incomplete addresses. Standard Requires a close match and generates a moderate number of match candidates. Default. Relaxed Allows a loose match and generates the most match candidates, which increases the processing time and results in more multiple matches. Use this mode if you are not confident that your input is clean; free of misspellings and incomplete addresses. Custom Provides the capability for you to define the matching criteria by setting MustMatch fields; however, you can only set the MustMatch fields using a POST request. For a GET request, the MustMatch default values are used. For more information on the MustMatch fields, refer to mustMatchFields. Interactive (USA only) Available in single-line address matching only. This mode is designed to better handle the specific matching challenges presented by interactive matching. Interactive mode permits for more flexible matching patterns and may, in some cases, return additional possible matches than relaxed match mode. CASS (USA only) Imposes additional rules to ensure compliance with the USPS CASS regulations. The purpose of this match mode is to create mailable addresses for USPS mailing discounts. Use this mode to standardize your input for mailing. This mode generates a large number of match candidates.
fallbackGeo	Boolean	Specifies whether to attempt to determine a geographic region centroid when an address-level geocode cannot be determined. Optional. True Return a geographic centroid when an address-level centroid cannot be determined. Default. False Do not return a geographic centroid when an address-level centroid cannot be determined.
fallbackPostal	Boolean	Specifies whether to attempt to determine a post code centroid when an address-level geocode cannot be determined. Optional. True Return a post code centroid when an address-level centroid cannot be determined. Default. False Do not return a post code centroid when an address-level centroid cannot be determined.
maxCands	Integer	The maximum number of candidates to return. Optional. Must be an integer value. Default = 1.
streetOffset	Double	Indicates the offset distance from the street segments to use in street-level geocoding. The distance is specified in the units you specify in the streetOffsetUnits option. Default value = 7 meters. The offset distance is used in street-level geocoding to prevent the geocode from being in the middle of a street. It compensates for the fact that street-level geocoding returns a latitude and longitude point in the center of the street where the address is located. Since the building represented by an address is not on the street itself, you do not want the geocode for an address to be a point on the street. Instead, you want the geocode to represent the location of the building which sits next to the street. For example, an offset of 50 feet means that the geocode will represent a point 50 feet back from the center of the street. The distance is calculated perpendicular to the portion of the street segment for the address. Offset is also used to prevent addresses across the street from each other from being given the same point. The following diagram shows an offset point in relation to the original point.
streetOffsetUnits	String	Specifies the unit of measurement for the street offset. One of the following: Feet Meters - Default
cornerOffset	Double	Specifies the distance to offset the street end points in street-level matching. The distance is specified in the units you specify in the cornerOffsetUnits option. This value is used to prevent addresses at street corners from being given the same geocode as the intersection. Defines the offset position of the geocoded point with respect to the corner. Default value = 7 meters. The following diagram compares the end points of a street to offset end points.
cornerOffsetUnits	String	Specifies the unit of measurement for the corner offset. One of the following: Feet Meters - Default