Address Reverse Geocode - Precisely Data Integrity Suite

Data Integrity Suite APIs
Product
Data_Integrity
Spatial_Analytics
Data_Enrichment
geo_addressing_1
Services
Spatial Analytics
Data Enrichment
Geo Addressing
ft:title
Data Integrity Suite APIs
ft:locale
en-US
PublicationType
pt_developer
copyrightfirst
2023
copyrightlast
2026

This section describes how to geocode one or more addresses using the Address Reverse Geocode API. You may want to try it out with a Free Trial Account.

This method will consume credits.
  • HTTP Request
    • URL Composition
      • Base URL: https://api.cloud.precisely.com
      • Geocode: /v1/reverse-geocode
    • Supported Methods: POST only
    • Rate Limit (Transactions per second): 700
    • Input Fields Each request to the API service requires a few parameters, all of which are listed below. All requests require a Bearer token, that can be generated using your account's key-secret. To produce a bearer token for an API request, the generated key-secret combinations are used. The generated token is valid for 3600sec (1 hour) and then it needs to be regenerated.

      The data should be encoded as a JSON array where each element in the array is a JSON object with field names identical to those in the input/output fields listed below.

      Table 1. Parameters
      Parameter Description Example Value

      X-Request-Id

      string      		 The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting 445677
      preferences Options supported by the Address Geocode Service which includes a variety of settings for match mode, geocode type, candidates returned, fallbacks, offsets, match address elements, range information, and more.

      maxResults: The maximum number of candidates to return. Optional. Must be an integer value.

      Default = 1.
      addresses List of addresses to be processed.

      addressLines:

      Requested address, based on the country's addressing standard.

      Single-line request:

      "10 downing street London SW1A 2AA"

      Multi-line request:

      "10 DOWNING STREET",

      "LONDON, SW1A 2AA"

Preferences

Below are the preferences for Address Reverse Geocode Service:

Option Type Description
clientCoordSysName String Specifies the coordinate system that you want to convert the geometry to. The format must be the European Petroleum Survey Group (EPSG) code or the SRID code. Default = EPSG:4326.

Specify the coordinate reference system in the format codespace:code.
cornerOffset

Distance

 Specify the distance to offset the street endpoints in street-level matching. This 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. The default is 7 meters.
data_option String Specifies the type of data option user opts for. Following are the available values for DATA_OPTION:
  • AddressBase
  • Premium (default)
  • Essentials
  • Enterprise
For example:
 "customPreferences": {
         "DATA_OPTION": "addressbase"
     }
distance Distance Define the search radius. The default is 5 meters.
fallbackToGeographic 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.
fallbackToPostal Boolean Specifies whether to attempt to determine a postcode centroid when an address-level geocode cannot be determined. Optional.
true
Return a postcode centroid when an address-level centroid cannot be determined. Default.
false
Do not return a postcode centroid when an address-level centroid cannot be determined.
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.
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.
maxResults Integer The maximum number of candidates to return. Default = 1.
returnAllInfo Boolean Specifies whether to return all available information for each candidate.
true
Return all available information for each candidate.
false
Do not return all available information for each candidate. Default.
returnOfAdditionalFields <String> array

This lets the user control which additional fields they want to have returned if they do not want to return all info.

For example, to return the Street segment identifier, use the value SEGMENT_ID
{
  "preferences" : {
    "returnOfAdditionalFields " : ["SEGMENT_ID"]
  }
}
streetOffset

Distance

 Specify the offset distance from the street segments to use in street-level geocoding. The offset prevents the geocode from being in the middle of a street.

The default is 7 meters.
type String

Indicates the geocode type to be performed.

ADDRESS
Geocode to a street address. Default.
GEOGRAPHIC
Geocode to the geographic centroid of a city or state.
POSTAL
Geocode to a postal code.

Custom Preferences

Below are the custom preferences for Address Geocode Service:
Table 2.
Option Type Description
ADDRESS_CASING String
Values are:
UPPER
uppercase
LOWER
lowercase
PROPER
sentence case
REVERSE_GEOCODE_DISTANCE String Distance of the radius in which to search for a match. METERS
REVERSE_GEOCODE_DISTANCE_UNIT Integer

Unit for Distance Unit.

FEET,METERS,MILES,KILOMETERS,

FOOT,METER,MILE,KILOMETER
GEOCODE_TYPE String

Set the type of geocode. Values are:

GEOGRAPHIC/POSTAL

ADDRESS (default)
MATCH_ON_ADDRESS_NUMBER Boolean When set to true, a match must be made to the input address number. When set to false, a match need not be made to the input address number. By default this preference is set to false.
MATCH_ON_ADMIN1 Boolean When set to true, a match be made to the input AreaName1 field. When set to false, a match need not be made to the input AreaName1 field. By default this preference is set to false.
MATCH_ON_ADMIN2 Boolean When set to true, a match be made to the input AreaName2 field. When set to false, a match need not be made to the input AreaName2 field. By default this preference is set to false.
MATCH_ON_CITY Boolean When set to true, a match be made to the input AreaName3 field. When set to false, a match need not be made to the input AreaName3 field. By default this preference is set to false.
MATCH_ON_NEIGHBORHOOD Boolean When set to true, a match be made to the input AreaName4 field. When set to false, a match need not be made to the input AreaName4 field. By default this preference is set to false.
MATCH_ON_POSTAL_CODE Boolean When set to true, a match be made to the input PostalCode1 field. When set to false, a match need not be made to the input PostalCode2 field. By default this preference is set to false.
MATCH_ON_POSTAL_CODE_EXT Boolean When set to true, a match be made to the input PostalCode2 field. When set to false, a match need not be made to the input PostalCode2 field. By default this preference is set to false.
MATCH_ON_PLACE_NAME Boolean When set to true, a match be made to the input PlaceName field. When set to false, a match need not be made to the input PlaceName field. By default this preference is set to false.
MATCH_ON_STREET_NAME Boolean When set to true, a match be made to the input StreetName field. When set to false, a match need not be made to the input StreetName field. By default this preference is set to false.
RETURN_FORMATTED_ADDRESS Boolean When set to true, the Address Lines in the output will be returned in the country-specific postal format for the candidate address. By default, this preference is set to false.
RETURN_PARSED_INPUT Boolean
The Parsed Input address displays the formatted input street address and each input address element in a separate field. This feature can help you understand how the input address was parsed by the geocoder and identify specific input elements that could not be geocoded. For example, a returned PARSED_INPUT_ADDRESS_NUMBER could contain an invalid house number in your input address. Optional.
true
Return parsed input address element in GeocodeServiceResponse object.
false
Do not return parsed input address element in GeocodeServiceResponse object. Default.
USE_ADDRESS_POINT_INTERPOLATION Boolean Address point interpolation is a patented process that results in a more accurate interpolated point. It improves upon regular street segment interpolation by using point data in the interpolation process, as opposed to using street segments alone.
PREFER_POBOX_OVER_STREET Boolean For countries that support PO Box addresses, this preference allows you to prefer the PO Box match over the Street match.
GEOHASH_LEVEL String Sets the precision of the geohash. By default, this is set to the highest level of precision, "12" characters. Enter a value "1" through "12".
RETURN_GEOHASH Boolean When set to true, returns the GEOHASH output field (LAT and LON custom fields as a 32-bit encoded string representing an area in . Default = false.)
REMOVE_ACCENT_MARKS Bolean When set to true diacritical marks are excluded in the output. Diacritical are accents and other symbols written above or below a letter to indicate a difference in pronunciation. By default, these marks display in the output.
RETURN_ALT_LANG_FIELDS Boolean When set to true, the input address is converted to the alternate language supported by the geocoder. By default, this preference is set to false.
FALLBACK_TO_STREET_CENTROID Boolean When set to true, it returns the street centroid level match (S4) for input with no matching house number. By default, this preference is set to false.
RETURN_INPUT_HOUSE_ON_S4_MATCH Boolean When set to false, and there is no match on the input house number, the candidate returned will not contain a house number along with it. By default, this preference is true.
RETURN_H3HEX Boolean When set to true, returns Hierarchical hexagonal grid value. Default = false.

Request Parameters

The below table lists the request parameters for Address Geocode Service:

Parameter Type Description
addressId String Address Id for the request.
addressLines List Requested address, based on the country's addressing standard.

Single-line request:

"10 downing street London SW1A 2AA"
Multi-line request:
"10 DOWNING STREET",
"LONDON, SW1A 2AA"
addressNumber String House or building number.

"10" or "630"
admin1 String The largest geographic area, typically a state or province.

"New York".

admin2 String The secondary geographic area, typically a county or district.

"Douglas County".
borough String Unit of local government or other administrative subdivision.

"Vazira" or "Manhattan"
building String A roofed and walled structure built for permanent use.
city String Specifies a city or town name.

"New York City"
country String Values are based on the ISO 3166-1 standard for country codes (returned in alpha-2, alpha-3, or numeric format).
floor String Each level within a building.
neighborhood String A city subdivision or locality.

"Highlands Ranch"
placeName String If applicable, indicates the name of the candidate's place or building.

"PRIME MINISTER& FIRST LORD OF THE TREASURY"
postalCode String Main postal code.

"80125"
postalCodeExt String Secondary postal code, if one exists. For example, in the US, a ZIP+4 is 80125-8012.

"8012"
room String A single room within a building.
suburb String Mixed-use or residential area within commuting distance of a city or urban area.
unit String The unit number, such as "3B".
unitType String A group or suite of rooms within a building that are under common ownership or tenancy, typically having a common entrance. (APT, STE, FLAT, etc.).