---
title: "Provides intelligent suggestions for postal codes and city"
method: POST
path: "/v1/autocomplete/postal-city"
tags: ["Address Autocomplete"]
---

# Provides intelligent suggestions for postal codes and city

`POST /v1/autocomplete/postal-city`

## Request

- Base URL: `https://api.cloud.precisely.com`
- URL: `https://api.cloud.precisely.com/v1/autocomplete/postal-city`
- Auth: one of:
  - HTTP bearer
  - API key in header `Authorization`

The Autocomplete Postal-City API provides intelligent suggestions for postal codes and city names based on partial input provided by the user. It is designed to enhance user experience in various applications that involve postal codes and city selection.

The API suggestions can be controlled by the **type** field which determines whether the suggestions should be based on only postal code or only city or mix of postal code and city.

This is an optional field. If it is not provided then the suggestions will be mix of postal code and city based.

It can have 2 values:
- **POSTAL** : Suggestions will be based on postal codes only.

- **CITY** : Suggestions will be based on city only.

## Headers

- `X-Request-Id` string

## Request body

- AutocompletePostalCityRequest: Basic request structure for geo-addressing APIs
  - `preferences` Preferences: Preferences that will processed with the request
    - `maxResults` integer: The maximum number of candidates to return. Default = 1.
    - `returnAllInfo` boolean: Specifies whether to return all available information for each candidate.
    - `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.
    - `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
    - `fallbackToGeographic` boolean: Specifies whether to attempt to determine a geographic centroid when an address-level geocode cannot be determined. Optional.
    - `fallbackToPostal` boolean: Specifies whether to attempt to determine a post code centroid when an address-level geocode cannot be determined. Optional.
    - `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.

## Response `200`

Address predicted successfully

- AutocompletePostalCityResponse: Response for autocomplete postal-city
  - `response` AutocompletePostalCityPredictionResponse: Prediction response for postal-city request
    - `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', required: Status
    - `errorMessage` string: Error message from the underlying service
    - `predictions` AutocompletePostalCityPredictionResult[]: List of AutoComplete Responses
      - `address` AutocompletePostalCityResponseAddress: Displays the components of the postal-city response address
        - `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
        - `postalCode` string: Postal code
      - `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

## Other responses

- `400`: Invalid request for Autocomplete Postal City API
- `401`: Unauthorized: Invalid token for Autocomplete Postal City API
- `403`: Forbidden fo rAutocomplete Postal City API
- `429`: Too many requests for Autocomplete Postal City API
- `500`: Internal server error fo Autocomplete Postal City API
- `503`: Autocomplete Postal City 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)