Enhances address autocompletion
This API provides enhanced and faster address autocompletion. The Address Autocomplete Express API offers advanced type-ahead capabilities. It quickly generates match candidates with just the initial characters of a place or address. As more characters are typed, the API refines results to display highly relevant candidates. With optimized performance, this API ensures a quicker and more efficient user experience. The Address Autocomplete Express API also supports global coverage, ensuring comprehensive and accurate address suggestions worldwide.
The Address Autocomplete Express API supports custom preferences, allowing you to specify the SEARCH_TYPE for each request. The available values for SEARCH_TYPE are: ADDRESS, POI, and AUTO.
List of supported countries for Address Autocomplete Express API with applicable SEARCH_TYPE:
| SEARCH_TYPE | COUNTRY |
|---|---|
| ADDRESS | EGY (ar-egy), AUS, CAN, CHN, COL, DEU, EGY, ESP, GBR, HKG, JPN (ja-jpn), JPN, JPN (ka-jpn), NLD, NZL, RUS (ru-rus), RUS, THA (th-tha), THA, TWN, USA, IRL, PRT, FRA, SWE, DNK, NOR, CHN (zh-chn), HKG (zh-hkg), TWN (zh-twn) |
| AUTO | EGY (ar-egy), AUS, CAN, CHN, COL, DEU, EGY, ESP, GBR, HKG, JPN (ja-jpn), JPN, JPN (ka-jpn), NLD, NZL, RUS (ru-rus), RUS, THA (th-tha), THA, TWN, USA, IRL, PRT, FRA, SWE, DNK, NOR, CHN (zh-chn), HKG (zh-hkg), TWN (zh-twn) |
| POI | USA, CAN, GBR, CHN, JPN, HKG, THA, TWN, EGY, RUS, COL, AUS |
Note: This API is only available in US region.
Request
- Base URL: https://api.cloud.precisely.com
- URL: https://api.cloud.precisely.com/v1/express-autocomplete
- Auth: one of:
- HTTP bearer
- API key in header Authorization
Headers
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. The maximum allowed length is 38 characters.
To handle a large number of calls and keep things organized, we group API calls for the same address into a single "transaction."
A transaction is considered complete when:
- 15 seconds have passed, or
- 12 API calls have been made, whichever happens first.
Transaction ID Behavior:
- 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:
1. 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.
2. 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 12-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.
Request body
Example request
{
"preferences": {
"maxResults": 1,
"returnAllInfo": true,
"factoryDescription": {
"label": "asd",
"featureSpecific": {
"LOOKUP": "ggs"
}
},
"customPreferences": {
"DATA_OPTION": "PREMIUM"
},
"clientLocale": {
"language": "en",
"script": "Latn",
"country": "US",
"variant": "POSIX",
"unicodeLocaleAttributes": [
"attribute1",
"attribute2"
],
"unicodeLocaleKeys": {
"nu": "thai"
},
"extensionKeys": {
"x": "private-use"
}
},
"clientCoordSysName": "EPSG:4326",
"distance": {
"value": 5,
"distanceUnit": "METER"
},
"streetOffset": {
"value": 5,
"distanceUnit": "METER"
},
"cornerOffset": {
"value": 5,
"distanceUnit": "METER"
},
"matchMode": "EXACT",
"originXY": [
0,
0
],
"returnOfAdditionalFields": [
"RESULT_CODE",
"PRECISION_CODE"
]
}
}Response
Address predicted successfully
Example response
{
"response": {
"errorMessage": "Not able to identify ABC country",
"status": "OK",
"predictions": [
{
"score": 95,
"addressLines": [
"350 Jordan Ave",
"Montoursville PA 17754"
],
"explanation": {
"identifier": "Geocoder",
"addressMatch": {
"description": [
{
"label": "streetName",
"matchType": "EXACT",
"returnType": "INPUT",
"matchedSubstring": "350 Jordan"
}
],
"type": "STREET"
},
"source": {
"label": "ggs"
}
},
"address": {
"street": "DISTRICT",
"formattedAddress": "1700 DISTRICT AVE STE 300, BURLINGTON MA 01803-5231, United States",
"formattedStreetAddress": "1700 DISTRICT AVE STE 300",
"formattedLocationAddress": "BURLINGTON, MA 01803-5231",
"addressNumber": "630",
"country": {
"name": "UNITED STATES",
"isoAlpha2Code": "US",
"isoAlpha3Code": "USA",
"isoNumericCode": "840"
},
"admin1": {
"longName": "New York or Maharashtra",
"shortName": "NY"
},
"admin2": {
"longName": "New York or Maharashtra",
"shortName": "NY"
},
"city": {
"longName": "New York or Maharashtra",
"shortName": "NY"
},
"borough": {
"longName": "New York or Maharashtra",
"shortName": "NY"
},
"neighborhood": {
"longName": "New York or Maharashtra",
"shortName": "NY"
},
"suburb": {
"longName": "New York or Maharashtra",
"shortName": "NY"
},
"postalCode": "80125",
"postalCodeExt": "8012",
"placeName": "PRIME MINISTER & FIRST LORD OF THE TREASURY",
"building": "Empire State",
"floor": "65",
"room": "A1",
"unit": "3B",
"unitType": "STE"
},
"location": {
"explanation": {
"type": "ADDRESS_POINT",
"description": "STREET_BLOCK",
"designation": "CENTROID",
"additionalMetadata": {
"SOURCE": "PRECISELY"
}
},
"feature": {
"geometry": {
"type": "Point",
"coordinates": [
-73.704719,
42.682251
],
"foreignMembers": {
"city": "New York",
"population": "8419600",
"founded": "1624"
}
},
"properties": {
"crsName": "epsg:4326"
},
"type": "Feature"
}
},
"customFields": {
"NAME_SHORT": "DISTRICT",
"PLACE": "2509875",
"CITY_SHORT": "BURLINGTON"
},
"parsed": [
{
"score": 0,
"classifications": [
{
"label": "street",
"value": "DISTRICT"
}
]
}
],
"iso20022": {
"address": {
"type": "PostalAddress27",
"format": "STRUCTURED",
"elements": {
"StrtNm": "Main Street",
"BldgNb": "123",
"BldgNm": "Tech Plaza",
"UnitNb": "5A",
"Room": "301",
"PstBx": "PO Box 456",
"PstCd": "12345",
"TwnNm": "Springfield",
"TwnLctnNm": "Downtown",
"DstrctNm": "Central District",
"CtrySubDvsn": "CA",
"Ctry": "US"
}
}
}
}
]
}
}Changes
No recorded changes to this operation across all 1 revision of this API.