--- title: "Enhances address autocompletion" method: POST path: "/v2/express-autocomplete" tags: ["Address Autocomplete Express"] --- # Enhances address autocompletion `POST /v2/express-autocomplete` ## Request - Base URL: `https://api.cloud.precisely.com` - URL: `https://api.cloud.precisely.com/v2/express-autocomplete` - Auth: one of: - HTTP bearer - API key in header `Authorization` 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. **SEARCH_TYPE** (via `customPreferences`): The API supports two values for `SEARCH_TYPE`: - **`ADDRESS`** — Returns address-based autocomplete candidates. This is the **default** when `SEARCH_TYPE` is not specified or omitted. - **`POI`** — Returns Point of Interest autocomplete candidates. List of supported countries for Address Autocomplete Express API with applicable **SEARCH_TYPE**: | SEARCH_TYPE | COUNTRY | |-------------|-------------| | ADDRESS (default) | 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. **Native Script Support** (via `preferences.clientLocale`): Use `clientLocale` to specify the language for native-script autocomplete results (optional, ISO 639-1 code). Supported values: `zh` (Chinese), `ja` (Japanese standard), `ka` (Japanese Katakana), `ru` (Russian), `th` (Thai), `ar` (Arabic). **filterBias** (via `preferences.filterBias`): The v2 API supports biasing and filtering results via `filterBias`. Set `type` to `"filter"` to strictly restrict results, or `"bias"` to promote matching results while still returning others. - **`filter`** — supports both `fields.include` and `fields.exclude`. Supported include keys: `city`, `postalCode`, `poiCategory`. - **`bias`** — supports `fields.include` only (`fields.exclude` is not allowed and will return an INVALID_REQUEST error). Supported include keys: `city`, `postalCode`. > **Note**: `poiCategory` is only valid when `SEARCH_TYPE` is `POI` and `filterBias.type` is `filter`. Using it with ADDRESS search or `type: bias` will return an INVALID_REQUEST error. **distance** (via `preferences.distance`): Defines the search radius around the input address. Example: `{"value": 150.0, "distanceUnit": "METER"}`. ## Headers - `X-Request-Id` string - `X-Transaction-Id` string ## Request body - AutocompleteV2Request: Request for autocomplete express V2 - `preferences` AutocompleteV2Preferences: This class uses ExpressPreferences to add FilterBias for Autocomplete Express Functionality - `fallbackToPostal` boolean: Specifies whether to attempt to determine a post code centroid when an address-level geocode cannot be determined. Optional. - `returnAllInfo` boolean: Specifies whether to return all available information for each candidate. - `fallbackToGeographic` boolean: Specifies whether to attempt to determine a geographic centroid when an address-level geocode cannot be determined. Optional. - `distance` Distance: 'distance' displays the defined search radius (default is 5 meters). 'streetOffset' specifies the offset distance from the street segments to use in street-level geocoding. 'cornerOffset' specifies the distance to offset the street end points in street-level matching (default is 7 meters). - `value` number, double: Distance of the radius in which to search for a match. Default is 5. - `distanceUnit` 'FOOT' | 'METER' | 'MILE' | 'KILOMETER': Distance unit - `streetOffset` Distance: 'distance' displays the defined search radius (default is 5 meters). 'streetOffset' specifies the offset distance from the street segments to use in street-level geocoding. 'cornerOffset' specifies the distance to offset the street end points in street-level matching (default is 7 meters). - `value` number, double: Distance of the radius in which to search for a match. Default is 5. - `distanceUnit` 'FOOT' | 'METER' | 'MILE' | 'KILOMETER': Distance unit - `cornerOffset` Distance: 'distance' displays the defined search radius (default is 5 meters). 'streetOffset' specifies the offset distance from the street segments to use in street-level geocoding. 'cornerOffset' specifies the distance to offset the street end points in street-level matching (default is 7 meters). - `value` number, double: Distance of the radius in which to search for a match. Default is 5. - `distanceUnit` 'FOOT' | 'METER' | 'MILE' | 'KILOMETER': Distance unit - `maxResults` integer: The maximum number of candidates to return. Default = 1. - `factoryDescription` FactoryDescription: Controls which address processor will process the request. - `label` string: Sets the addressing processor based on the configured data. Labels are case-sensitive and must be lowercase. Default is "". - `featureSpecific` object: Ability to map a feature to an address processor, based on specified label. - `GEOCODE` string - `PARSE` string - `VERIFY` string - `REVERSE_GEOCODE` string - `INTERACTIVE` string - `LOOKUP` string - `customPreferences` object: For use against any country dataset, define custom preferences to control additional functionality such as matching criteria, address casing, and enable functionality like DPV and SuiteLink. - `clientLocale` Locale: Represents a locale with language, script, country, and variant information. - `language` string: The ISO 639 language code. - `script` string: The ISO 15924 script code. - `country` string: The ISO 3166 country code. - `variant` string: The variant code for the locale. - `unicodeLocaleAttributes` string[]: The Unicode locale attributes. - `unicodeLocaleKeys` object: The Unicode locale keys. - `extensionKeys` object: The extension keys. - `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. - `matchMode` string: Match modes determine the leniency used to make a match between the input address and the reference data. - `originXY` number[]: XY coordinates of the origin address. - `returnOfAdditionalFields` string[]: This lets the user control which additional fields they want to have returned if they do not want to return all info. - `filterBias` FilterBias: 'filterBias' contains the information about bias fields and their values. 'include' specifies the fields to be included for biasing the results. 'exclude' specifies the fields to be filtered - `type` 'bias' | 'filter': Contains the value of the filterBias type, either bias or filter - `fields` FilterBiasFields, required: 'fields' specifies which fields to be included or excluded in the biasing - `include` object: Specifies which fields to be included biasing - `exclude` object, nullable: Specifies which fields to be excluded in filters - `address` RequestAddress, required: Request address that will be processed - `city` string: Specifies a city or town name. - `street` string: Street name only (no directional or street suffix). - `admin2` string: The secondary geographic area, typically a county or district. - `placeName` string: If applicable, indicates the name of the candidate's place or building. - `addressNumber` string: House or building number. - `suburb` string: Mixed-use or residential area within commuting distance of a city or urban area. - `neighborhood` string: A city subdivision or locality. - `admin1` string: The largest geographic area, typically a state or province. - `postalCode` string: Main postal code. - `floor` string: Each level within a building. - `postalCodeExt` string: Secondary postal code, if one exists. For example, in the US, a ZIP+4 is 80125-8012. - `room` string: A single room within a building. - `borough` string: Unit of local government or other administrative subdivision. - `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.). - `building` string: A roofed and walled structure built for permanent use. - `country` string, required: Values are based on the ISO 3166-1 standard for country codes (returned in alpha-2, alpha-3, or numeric format). - `addressLines` string[]: Requested address, based on the country's addressing standard. ## Response `200` Address predicted successfully - AutocompleteResponse: Response for autocomplete - `response` PredictionResponse: Prediction response for request - `errorMessage` string: Error message from the underlying service - `status` 'OK' | 'ZERO_RESULTS' | 'UNKNOWN_ERROR' | 'INVALID_REQUEST' | 'SERVICE_UNAVAILABLE' | 'INTERNAL_ERROR' | 'INVALID_CLIENT_INPUT' | 'INVALID_TOKEN' | 'BATCH_SIZE_EXCEEDED' | 'FORBIDDEN' | 'TOO_MANY_REQUESTS' | 'REQUEST_TIMEOUT': Status - `predictions` PredictionResult[]: List of prediction results - `score` integer: Provides a number from 0-100 to indicate how much the input was changed in order to match to the output candidate. - `addressLines` string[]: Displays multiple formatted lines to support the postal standard of a given country. - `explanation` Explanation: Describes the level of matching for each component of an address - `identifier` string: An ID generated from the underlying source reference data of an address. - `addressMatch` AddressMatch: Describes the quality of address matching based on the user input address - `description` MatchDescription[]: list of match descriptions - `label` string: Label for matching - `matchType` string: EXACT, PARTIAL, ALIAS_EXACT, ALIAS_PARTIAL, ADDED, REMOVED, NONE - `returnType` string: INPUT, PREFERRED, ALIAS, PARTIAL, NONE - `matchedSubstring` string: For the Predict service, returns the portion of the input that matched against the output. - `type` 'ADDRESS' | 'STREET' | 'ADMIN' | 'POBOX' | 'POI' | 'NOMATCH': Match type - `source` object: Returns information about the address processor. - `address` ResponseAddress: Displays components of the address - `street` string: Street name only (no directional or street suffix). - `formattedAddress` string: All components of the address, formatted to the country's standard, on one line. - `formattedStreetAddress` string: Street portion of the address, including the directional and street suffix, formatted to the country's standard. - `formattedLocationAddress` string: Location portion of the address, formatted to the country's standard. - `addressNumber` string: House or building number. - `country` CountryField: Values are based on the ISO 3166-1 standard for country codes (returned in alpha-2, alpha-3, or numeric format) - `name` string: Common name of the country - `isoAlpha2Code` string: Alphabetic code (alpha-2) - `isoAlpha3Code` string: Alphabetic code (alpha-3) - `isoNumericCode` string: Numeric code (numeric-3) - `admin1` AdminField: Specifies the geographic area like: admin1, admin2, city, neighborhood, suburb, borough. - `longName` string: Long name - `shortName` string: Short name - `admin2` AdminField: Specifies the geographic area like: admin1, admin2, city, neighborhood, suburb, borough. - `longName` string: Long name - `shortName` string: Short name - `city` AdminField: Specifies the geographic area like: admin1, admin2, city, neighborhood, suburb, borough. - `longName` string: Long name - `shortName` string: Short name - `borough` AdminField: Specifies the geographic area like: admin1, admin2, city, neighborhood, suburb, borough. - `longName` string: Long name - `shortName` string: Short name - `neighborhood` AdminField: Specifies the geographic area like: admin1, admin2, city, neighborhood, suburb, borough. - `longName` string: Long name - `shortName` string: Short name - `suburb` AdminField: Specifies the geographic area like: admin1, admin2, city, neighborhood, suburb, borough. - `longName` string: Long name - `shortName` string: Short name - `postalCode` string: Main postal code. - `postalCodeExt` string: Secondary postal code, if one exists. For example, in the US, a ZIP+4 is 80125-8012. - `placeName` string: If applicable, indicates the name of the candidate's place or building. - `building` string: A roofed and walled structure built for permanent use. - `floor` string: Each level within a building. - `room` string: A single room within a building. - `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.). - `location` Location: Describes the location type and coordinates - `explanation` LocationExplanation: Provides location quality and precision - `type` 'ADDRESS_POINT' | 'INTERSECTION' | 'ADDRESS_INTERPOLATED' | 'NEAR_BY_ADDRESS' | 'STREET' | 'STREET_CENTER' | 'STREET_BLOCK' | 'POSTAL' | 'POSTAL_CENTROID' | 'SUB_TOWN_CENTROID' | 'TOWN_CENTROID' | 'ADMIN1' | 'ADMIN1_CENTROID' | 'ADMIN2' | 'ADMIN2_CENTROID' | 'CITY' | 'NEIGHBORHOOD' | 'SUBURB' | 'COUNTRY' | 'UNKNOWN' | 'NO_LOCATION' | 'POI' | 'POSTAL_BUILDING' | 'PO_BOX': Location type - `description` 'POSTAL_BUILDING' | 'INTERSECTION' | 'STREET_BLOCK' | 'PO_BOX' | 'PO_BLOCK' | 'BUILDING' | 'PROJECTED_POINT' | 'POSTAL_CODE' | 'POSTAL_CODE_EXT' | 'POINT_OF_INTEREST' | 'PARCEL' | 'FRONT_DOOR' | 'DRIVEWAY' | 'STREET_ACCESS_POINT' | 'PARCEL_POINT' | 'BACKFILL_POINT' | 'VIRTUAL_POINT' | 'DOOR' | 'ROOM' | 'BACK_DOOR' | 'BUILDING_ENTRANCE' | 'EAST_SIDE_DOOR' | 'WEST_SIDE_DOOR' | 'SOUTH_SIDE_DOOR' | 'NORTH_SIDE_DOOR' | 'ENTRANCE' | 'IOT_DEVICE': Location description types - `designation` 'CENTROID' | 'CENTER_LINE_PROJECTED' | 'MODIFIED_SEGMENT_WITH_POINT' | 'CALCULATED_WITH_PARCEL_AND_CENTERLINE' | 'RELATIVE_TO_STREET' | 'RELATIVE_TO_MULTI_PARCEL' | 'RELATIVE_TO_PARCEL_AND_STREET_CENTER' | 'CALCULATED_WITH_STREET_SEGMENTS' | 'INTERPOLATED_INTERSECTION' | 'MIDPOINT_BETWEEN_RANGE' | 'MULTIPLE_USPS_SEGMENTS' | 'SEGMENT_WITHOUT_SHAPE' | 'CALCULATED_WITH_USER_DATA' | 'CALCULATED_WITH_POINT_AND_STREET' | 'CALCULATED_WITH_TWO_STREET_SEGMENTS': Location designation types - `additionalMetadata` object: Any additional metadata about the location - `feature` SimpleFeature: SimpleFeature object with geometry and additional properties - `geometry` Geometry: Provides the candidate's geometry - `type` string: Geometry type. The return value is always Point - `coordinates` number[]: Coordinates as x (longitude) and y (latitude) separated by a comma - `foreignMembers` object: Foreign Members - `properties` object: crsName - The coordinate reference system (CRS) used for the candidate's geocode. Expressed in epsg:nnnn format; the default is epsg:4326 - `type` string: Feature - `customFields` object: Returns additional information about the address. - `parsed` ParsedAddress[]: list the details of parsed request address - `score` integer: Score of parsed address - `classifications` ParsedFieldClassification[]: list the parsed address fields - `from` string: from - `label` string: label - `value` string: value - `start` integer: start - `end` integer: end - `iso20022` ISO20022Format: ISO 20022 formatted address response following the PostalAddress27 structure - `address` ISO20022Address: ISO 20022 PostalAddress27 structure containing address type, format, and elements - `type` string: Type of postal address structure according to ISO 20022 standard - `format` string: Format of the address representation - `elements` ISO20022AddressElements: ISO 20022 address elements containing structured address components according to PostalAddress27 - `StrtNm` string: Street name (StrtNm) - Name of the street or thoroughfare - `BldgNb` string: Building number (BldgNb) - Number that identifies the position of a building on a street - `BldgNm` string: Building name (BldgNm) - Name of the building or house - `UnitNb` string: Unit number (UnitNb) - Number that identifies a unit within a building - `Room` string: Room (Room) - Information that identifies a room within a building - `PstBx` string: Post box (PstBx) - Numbered box in a post office assigned to a person or organization - `PstCd` string: Postal code (PstCd) - Identifier used by postal services to identify postal zones or geographic areas - `TwnNm` string: Town name (TwnNm) - Name of the town or city - `TwnLctnNm` string: Town location name (TwnLctnNm) - Name that identifies a subdivision within a town or city - `DstrctNm` string: District name (DstrctNm) - Name that identifies a territorial division or district - `CtrySubDvsn` string: Country subdivision (CtrySubDvsn) - State, province, or region within a country - `Ctry` string: Country (Ctry) - Country code in ISO 3166-1 alpha-2 format ## Other responses - `400`: Invalid request for Autocomplete Express API - `401`: Unauthorized: Invalid token for Autocomplete Express API - `403`: Forbidden for Autocomplete Express API - `429`: Too many requests for Autocomplete Express API - `500`: Internal server error for Autocomplete Express API - `503`: Autocomplete Express Service unavailable --- [API](https://skmtc.dev/precisely/apis/geo-addressing-api.md) · [All operations](https://skmtc.dev/precisely/apis/geo-addressing-api/llms.txt) · [OpenAPI document](https://skmtc.dev/precisely/apis/geo-addressing-api/revisions/d985d4737abe?raw)