--- title: "Finds the addresses using a unique identification ID" method: POST path: "/v1/lookup" tags: ["ID Lookup"] --- # Finds the addresses using a unique identification ID `POST /v1/lookup` ## Request - Base URL: `https://api.cloud.precisely.com` - URL: `https://api.cloud.precisely.com/v1/lookup` - Auth: one of: - HTTP bearer - API key in header `Authorization` This API allows to find an address using a PreciselyID unique identifier as input and return all standard returns that are provided as part of address matching. **Note**: Currently, no preferences are honored for this ID Lookup API. ## Headers - `X-Request-Id` string ## Request body - LookupRequest: 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` ID lookup successfully - LookupResponse: Response for ID lookup - `responses` Response[]: list of lookup responses - `addressId` string: Address Id of the response - `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 - `results` Result[]: List of 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 - `206`: ID lookup partially - `400`: Invalid request for Lookup API - `401`: Unauthorized: Invalid token for Lookup API - `403`: Forbidden for Lookup API - `413`: Request entity too large for Lookup API - `429`: Too many requests for Lookup API - `500`: Internal server error for Lookup API - `503`: Lookup 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)