Address Autocomplete - 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 address autocomplete works for one or more addresses using the Address Autocomplete 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
      • Address Autocomplete: /v1/autocomplete
    • Supported Methods: POST only
    • Rate Limit (Transactions per second): 120
    • 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
      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, ranges 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"
      Below is a sample request with an address request to Address Autocomplete Service
      {
  "preferences": {
    "maxResults": 2,
    "returnAllInfo": true,
    "factoryDescription": {
      "label": "",
      "featureSpecific": {}
    },
    "clientLocale": "",
    "clientCoordSysName": "",
    "distance": {
      "value": 150,
      "distanceUnit": "METER"
    },
    "streetOffset": {
      "value": 7,
      "distanceUnit": "METER"
    },
    "cornerOffset": {
      "value": 7,
      "distanceUnit": "METER"
    },
    "fallbackToGeographic": false,
    "fallbackToPostal": false,
    "matchMode": "",
    "returnOfAdditionalFields": false,
    "originXY": [],
    "customPreferences": {}
  },
  "address": {
    "addressLines": [
      "350 Jordan"
    ],
    "country": "USA",
    "addressNumber": "",
    "admin1": "",
    "admin2": "",
    "city": "",
    "borough": "",
    "neighborhood": "",
    "suburb": "",
    "postalCode": "",
    "postalCodeExt": "",
    "placeName": "",
    "street": "",
    "building": "",
    "floor": "",
    "room": "",
    "unit": "",
    "unitType": ""
  } 
}

Preferences

Below are the preferences for Address Autocomplete 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.
Note: The API always returns the output coordinates in EPSG:4326, regardless of the input coordinate system.
customPreferences

Object

 Custom preference are optional preferences which are used to control certain additional functionalities please see the list of custom preferences for details.
distance Distance Define the search radius. The default is 5 meters.
maxResults Integer The maximum number of candidates to return. Default = 1.
originXY <Double> array XY coordinates of the origin address. 
{
"preferences" : 
  {
  "originXY" : [-73.70252500000001, 42.68323]
    },
  "address" : 
  {
  "mainAddressLine" : "350 Jordan Rd"
  }
}
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 PreciselyID, use the value PB_KEY
{
  "preferences" : {
    "returnOfAdditionalFields " : ["PB_KEY"]
  }
}
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.

Request Parameters

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

Parameter Type Description
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" or "Maharashtra".

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

"Douglas County" or "West Mumbai".
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.).

X-Request-Id

(header)

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.
X-Transaction-Id

(header)

 String

To efficiently manage a high volume of API calls and maintain organization, we group API calls for the same address into a single "transaction." A transaction is considered complete when one of the following conditions is met:

  • 15 seconds have passed
  • 12 API calls have been made

whichever happens first.

The Transaction ID (GUID) must be sent as part of the x-transaction-id header in each API request. We recommend users generate a new Transaction ID for every new transaction.

If the same Transaction ID is reused after a transaction is marked complete, our system will treat it as a new transaction while keeping the same ID.

Examples:

15-Second Scenario: A user starts typing an address and includes a Transaction ID (e.g., 1234-5678-ABCD) in the x-transaction-id header:
  • They make 4 calls (e.g., for "12", "123", "123 Main", "123 Main St") within 15 seconds.
  • After 15 seconds, the transaction is marked complete.
  • If the user's input is still not finished (e.g., they want to add "Apt 4") and they continue using the same Transaction ID (1234-5678-ABCD), our system will treat these additional calls as part of a new transaction.
12-Call Scenario: Another user types quickly and includes a Transaction ID (e.g., 5678-1234-EFGH) in the x-transaction-id header:
  • They make 12 calls (e.g., for "1", "12", "123", ..., "123 Main St Apt 4") within 3 seconds.
  • Since the 8-call limit is reached, the transaction is marked complete.
  • If the user continues to refine or add to their input using the same Transaction ID (5678-1234-EFGH), our system will treat these additional calls as part of a new transaction.