--- title: "Search and format a list of suggestions." method: POST path: "/address/suggestions/format/v1" tags: ["Address Validation"] --- # Search and format a list of suggestions. `POST /address/suggestions/format/v1` ## Headers - `Reference-Id` string - `Timeout-Seconds` integer - `Add-Components` boolean - `Add-Metadata` boolean ## Request body - AddressSuggestionsFormatV1Request — The address suggestions format v1 request. - `country_iso` string, required — The country ISO3 code of address. - `datasets` string[], required — The datasets for address validation. - `max_suggestions` integer, nullable — The maximum number of suggestions a search request should return (should be between 1 and 100). - `components` AddressInputComponents, required — The address search input component. - `unspecified` string[], nullable — The input component collection. - `names` AddressInputComponentName[], nullable — The names component. - `forename` string, nullable — The first name. - `middlename` string, nullable — Middle initial. - `surname` string, nullable — The surname. - `locality` AddressLocalityConstrains — A class representing search locality constraints - `region` AddressRestrictionRules — A class that represents address restriction rules - `exists` boolean, nullable — Gets or sets a value indicating whether the address element is required to exist for returned addresses or required to not exist. Null value means that both records with and without such element will be returned. - `must_be` string[], nullable — Gets or sets an array of values, causing the returned result to include only records that have one of the values - `must_not_be` string[], nullable — Gets or sets an array of values, causing the returned result to include only records that exclude the values - `layouts` string[], nullable — Custom layout name. ## Response `200` OK - AddressSuggestionsFormatV1Response — Response model for AddressSuggestionsFormatV1 endpoint. - `error` ResponseError — Error model containing the error details. - `type` string, nullable — A link to documentation that provides more details about the error you’ve encountered. - `title` string, nullable — The title of the error. - `detail` string, nullable — A description of the error. - `instance` string, nullable — The endpoint that returned the error. - `result` AddressSuggestionsFormatV1Result — Address suggestions format result. - `more_results_available` boolean — To indicate that there are more suggestions available than the results provided. - `confidence` string, nullable — The outcome (confidence level) of the validation. - `suggestions` AddressSuggestionsFormatV1[], nullable — The collection of the suggestions that match the address search input. - `global_address_key` string, nullable — The ID of the address received as part of a validation. - `address` Address7Lines — Seven address lines representing a formatted address for the chosen country. - `address_line_1` string, nullable — The first line of address containing a number of specific components relating to the premises and street. - `address_line_2` string, nullable — The second line of address containing a number of specific components relating to the premises and street. - `address_line_3` string, nullable — The third line of address containing a number of specific components relating to the premises and street. - `locality` string, nullable — The town, locality or suburb. - `region` string, nullable — The city, state code or province. - `postal_code` string, nullable — The post/zip code. - `country` string, nullable — The localised country name. - `addresses_formatted` AddressFormatted[], nullable — Customized address layouts. - `layout_name` string, nullable — The address layout name. - `not_enough_lines` boolean — There are not enough address lines configured to display the whole address. - `has_truncated_lines` boolean — Truncation has occurred on one or more address lines. - `address` object, nullable — The customized address layouts in default format. - `components` AddressComponent — The components that differ by country and address type. Note that parameters with blank values will not be returned. - `language` string, nullable — Address language. - `country_name` string, nullable — The name of the country where the address is located. - `country_iso_3` string, nullable — The 3-letter ISO country code. - `country_iso_2` string, nullable — The 2-letter ISO country code. - `country_iso_numeric` string, nullable — The numeric ISO country code. - `postal_code` AddressComponentPostalCode — The post code component. - `full_name` string, nullable — The full name of the postal code. - `primary` string, nullable — The primary name of the postal code. - `secondary` string, nullable — The secondary name of the postal code. - `delivery_service` AddressComponentDeliveryService — The delivery service component. - `full_name` string, nullable — The full name of the delivery service. - `service_type` string, nullable — The delivery service type. - `service_number` string, nullable — The delivery service number. - `post_centre_name` string, nullable — The delivery service post center name. - `secondary_delivery_service` AddressComponentDeliveryService — The delivery service component. - `full_name` string, nullable — The full name of the delivery service. - `service_type` string, nullable — The delivery service type. - `service_number` string, nullable — The delivery service number. - `post_centre_name` string, nullable — The delivery service post center name. - `sub_building` AddressComponentSubBuilding — The sub building component. - `name` string, nullable — The name of a building or property. - `entrance` AddressComponentSubBuildingItem — An item of sub-building information, such as a floor or entrance number or name. - `full_name` string, nullable — The full name of this subcomponent. - `type` string, nullable — The type of this subcomponent. - `value` string, nullable — The value of this subcomponent. - `floor` AddressComponentSubBuildingItem — An item of sub-building information, such as a floor or entrance number or name. - `full_name` string, nullable — The full name of this subcomponent. - `type` string, nullable — The type of this subcomponent. - `value` string, nullable — The value of this subcomponent. - `door` AddressComponentSubBuildingItem — An item of sub-building information, such as a floor or entrance number or name. - `full_name` string, nullable — The full name of this subcomponent. - `type` string, nullable — The type of this subcomponent. - `value` string, nullable — The value of this subcomponent. - `building` AddressComponentBuilding — The building component. - `building_name` string, nullable — The building name. - `secondary_name` string, nullable — The secondary building name. - `building_number` string, nullable — The building number. - `secondary_number` string, nullable — The secondary name of the building (if available). - `allotment_number` string, nullable — The allotment name where a person or property resides. - `organization` AddressComponentOrganization — The organization component. - `department_name` string, nullable — The department name within an organization. - `secondary_department_name` string, nullable — The secondary department name within an organization. - `company_name` string, nullable — The company name. - `business` AddressComponentBusinessOrganization — The business component. - `company_name` string, nullable — The company name from an additional business dataset. - `street` AddressComponentStreet — The street component. - `full_name` string, nullable — The combination of the other populated secondary street components: prefix, name, type, suffix. - `prefix` string, nullable — The street prefix only. - `name` string, nullable — The street name only. - `type` string, nullable — The street type only. - `suffix` string, nullable — The street suffix only. - `secondary_street` AddressComponentStreet — The street component. - `full_name` string, nullable — The combination of the other populated secondary street components: prefix, name, type, suffix. - `prefix` string, nullable — The street prefix only. - `name` string, nullable — The street name only. - `type` string, nullable — The street type only. - `suffix` string, nullable — The street suffix only. - `route_service` AddressComponentRouteService — The route service component. - `full_name` string, nullable — The full name of the route service. - `service_type` string, nullable — The route service type. - `service_number` string, nullable — The route service number. - `delivery_name` string, nullable — The route service delivery name. - `qualifier` string, nullable — The route service qualifier. - `locality` AddressComponentLocality — The locality component. - `region` AddressComponentLocalityItem — A single place name, code and a description of its type. - `name` string, nullable — The name for this subcomponent. - `code` string, nullable — The code of this subcomponent. - `description` string, nullable — The description of this subcomponent. - `sub_region` AddressComponentLocalityItem — A single place name, code and a description of its type. - `name` string, nullable — The name for this subcomponent. - `code` string, nullable — The code of this subcomponent. - `description` string, nullable — The description of this subcomponent. - `town` AddressComponentLocalityItem — A single place name, code and a description of its type. - `name` string, nullable — The name for this subcomponent. - `code` string, nullable — The code of this subcomponent. - `description` string, nullable — The description of this subcomponent. - `district` AddressComponentLocalityItem — A single place name, code and a description of its type. - `name` string, nullable — The name for this subcomponent. - `code` string, nullable — The code of this subcomponent. - `description` string, nullable — The description of this subcomponent. - `sub_district` AddressComponentLocalityItem — A single place name, code and a description of its type. - `name` string, nullable — The name for this subcomponent. - `code` string, nullable — The code of this subcomponent. - `description` string, nullable — The description of this subcomponent. - `physical_locality` AddressComponentLocality — The locality component. - `region` AddressComponentLocalityItem — A single place name, code and a description of its type. - `name` string, nullable — The name for this subcomponent. - `code` string, nullable — The code of this subcomponent. - `description` string, nullable — The description of this subcomponent. - `sub_region` AddressComponentLocalityItem — A single place name, code and a description of its type. - `name` string, nullable — The name for this subcomponent. - `code` string, nullable — The code of this subcomponent. - `description` string, nullable — The description of this subcomponent. - `town` AddressComponentLocalityItem — A single place name, code and a description of its type. - `name` string, nullable — The name for this subcomponent. - `code` string, nullable — The code of this subcomponent. - `description` string, nullable — The description of this subcomponent. - `district` AddressComponentLocalityItem — A single place name, code and a description of its type. - `name` string, nullable — The name for this subcomponent. - `code` string, nullable — The code of this subcomponent. - `description` string, nullable — The description of this subcomponent. - `sub_district` AddressComponentLocalityItem — A single place name, code and a description of its type. - `name` string, nullable — The name for this subcomponent. - `code` string, nullable — The code of this subcomponent. - `description` string, nullable — The description of this subcomponent. - `additional_elements` AddressComponentAdditionalElements — The additional elements component. - `locality` AddressComponentAdditionalLocality — The additional locality component. - `sub_region` AddressComponentAdditionalSubRegion — The additional sub region component. - … - `metadata` AddressMetadata — The address metadata. - `address_info` AddressMetadataInfo — Address information. - `sources` string[], nullable — Source of address information. - `number_of_households` string, nullable — Number of households for records in GBR Not Yet Built, or multi-occupancy count of the owning delivery point for GBR Multiple Residence. - `just_built_date` string, nullable — Construction date of the record, if it has been constructed in the last 6 months (GBR specific). - `identifier` AddressMetadataInfoId — The ID metadata of formatted address. - `umrrn` string, nullable — Royal Mail's Unique Multiple Residence Reference Number, an eight-digit code linked to UDPRNs in Royal Mail's Multiple Residence dataset. - `udprn` string, nullable — Royal Mail's Unique Delivery Point Reference Number, an eight-digit code assigned to every delivery point in the Postcode Address File (PAF). - `uprn` string, nullable — Unique Property Reference Number, a unique 12-digit identifier for each land and property unit (AddressBase and AddressBase with Names). - `dpid` string, nullable — Australia Post's Delivery Point Identifier, an eight-digit number that uniquely identifies a physical location to which Australia Post delivers mail - applicable to AUS and NZL addresses. - `gnafPid` string, nullable — Geoscape Australia's Geocoded National Address File Persistent Identifier (G-NAF ID). - `paf_address_key` string, nullable — PAF Address key (GBR specific). - `hin` string, nullable — Household Identification Number (applicable for AUS addresses). - `organization_key` string, nullable — Unique 14-character key for the organization record. - `lpi_key` string, nullable — Unique 14-character key for the LPI record. - `dps` string, nullable — A two character code uniquely identifying an individual delivery point within a postcode. - `parent_uprn` string, nullable — The UPRN of the parent property associated with a record. - `building_id` string, nullable — This is a unique number which identifies each building or premises. - `barcode` AddressMetadataBarcode — Address barcode. - `delivery_point_barcode` string, nullable — The delivery point barcode (applicable for USA addresses only). - `check_digit` string, nullable — The delivery point barcode's check digit (applicable for USA addresses only). - `sort_plan_number` string, nullable — The sort plan number barcode (applicable for AUS addresses only). - `route_classification` AddressMetadataRouteClassification — Address deliverability and type indicators. - `carrier_route` string, nullable — The carrier route value (applicable for USA addresses only). - `id` string, nullable — The street identifier (applicable for AUS addresses only). - `elot` string, nullable — Contains a sequence number and an ascending/descending code. The number indicates the first occurrence of delivery made to the add-on range within the carrier route. The code indicates the approximate delivery order within the sequence number. - `roudis_id` string, nullable — This reference code provides an entry point into the ROUDIS2000 file provided by La Poste. - `address_classification` AddressMetadataAddressClassification — Address deliverability and type indicators. - `address_type` AddressMetadataAddressType — The address type. - `code` string, nullable — The code of the address type (applicable to USA, AUS and NZL addresses). - `description` string, nullable — The description of the address type (applicable to USA, AUS and NZL addresses). - `delivery_type` string, nullable — Type of mail delivery at the address. Either "business", "residential" or "mixed". - `is_deliverable` string, nullable — Indicator if the address is deliverable - applicable to NZL addresses only. - `dpv` AddressMetadataDpv — Delivery Point Validation information for the address (USA only). - `cmra_indicator` string, nullable — Indicates that the address is a private business that acts as a commercial mail-receiving agent for specific clients. - `seed_indicator` string, nullable — Seed records are control records placed by the USPS to prevent unauthorized tampering (e.g., creation of lists containing every single delivery point in a geographical region). A seed address will deactivate DPV functionality. To re-activate, please visit the Self Service Portal. - `dpv_indicator` string, nullable — Indicates whether selected address is confirmed as deliverable via DPV (Delivery Point Validation) process. For all possible values, please visit our technical documentation portal. - `footnotes` string[], nullable — USPS codes denoting DPV match levels. For a list of all possible values, please visit our technical documentation portal. - `vacancy_indicator` string, nullable — An address known to be unoccupied for over 90 days and therefore not receiving mail deliveries. - `no_stats_indicator` string, nullable — An address known to not receive mail deliveries (e.g. a house under construction). - `pbsa_indicator` string, nullable — Indicates addresses known to be Post Office Box Street Addresses (PBSA). - `lacs_indicator` string, nullable — Gets or sets the Locatable Address ConversionSystem Link Indicator. It links addresses that were converted due to USPS changes to their new addresses. This affects many rural addresses with assigned city-style names for 911 emergencies. - `lacs_code` string, nullable — Gets or sets the Locatable Address ConversionSystem Link Code. It links addresses that were converted due to USPS changes to their new addresses. This affects many rural addresses with assigned city-style names for 911 emergencies. - `urbanization` string, nullable — Gets or sets Urbanization property of the address. - `delivery_line_1` string, nullable — Gets or sets delivery line 1 of the address. - `delivery_line_2` string, nullable — Gets or sets delivery line 2 of the address. - `last_line` string, nullable — Gets or sets last line of the address. - `no_stat_reason_code` string[], nullable — Gets or sets DPV No stat reason code - `drop` string, nullable — Gets or sets DPV Drop indicator - `throwback` string, nullable — Gets or sets DPV Throwback indicator - `non_delivery_days_indicator` string, nullable — Gets or sets DPV Non Delivery Day indicator - `non_delivery_days_value` string[], nullable — Gets or sets DPV Non Delivery Week Days indicator - `no_secure_location` string, nullable — Gets or sets DPV No Secure Location indicator - `door_not_accessible` string, nullable — Gets or sets DPV Door Not Accessible indicator - `enhanced_dpv_code` string, nullable — Gets or sets Enhanced DPV Return Code - `firm_name` string, nullable — Gets or sets Firm Name field of the address. ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `406` — Not Acceptable - `408` — Request Timeout - `415` — Unsupported Media Type - `429` — Too Many Requests - `500` — Internal Server Error - `503` — Service Unavailable --- [API](https://skmtc.dev/experianaperture/apis/aperture-rest-api.md) · [All operations](https://skmtc.dev/experianaperture/apis/aperture-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/experianaperture/aperture-rest-api/revisions/f17d329b4892/schema)