{ "openapi": "3.0.1", "info": { "title": "Geo Addressing API", "description": "The Precisely Data Integrity Suite offers Geo Addressing services for address validation, standardization, geocoding, reverse geocoding, and address autocomplete.\n\nThe APIs use the premium data option (Option3) as default for the processing.\n\nOption 1 and Option 2[New]: We recently have introduced essentials (Option1) data option to specifically support the entry level street datasets and enterprise data option (Option2) to specifically support the postal datasets. This support has been added to the verify, geocode and autocomplete APIs. The user will be able to access these data options based on their entitlements.\n\nNote: User having access with multiple data option, can specify a custom preference named 'DATA_OPTION' with values 'essentials', 'enterprise' or 'premium' in their custom preferences. The API response will be tailored accordingly based on this preference.\nMulti-vintage data is now exclusively available with a premium dataset subscription, this allows users to access data from dual vintages i.e. the current and the previous vintage. The Multi- vintage support is implemented through a custom preference DATA_VERSION which accepts value in YYYY-MM format.\n
\n Error Codes\n\nAPIs will return the following error codes in case of any error:\n\n\n| Error Code | Description\n|----------------------------|-------------------------------------------------------\n| DIS-1001 | Unauthorized, Invalid token\n| DIS-1002 | Not Authorized to access this API\n| DIS-1003 | Issue with internal services\n| DIS-1004 | Workspace Id is missing from Bearer Token\n| DIS-1005 | Rate limit exceeded\n| DIS-1006 | Unauthorized, Invalid key/secret\n| DIS-1007 | API quota has been permanently exhausted. No further requests are allowed for trial user\n| DIS-1009 | Access blocked due to too many failed attempts. Please try again after sometime\n| DIS-1010 | Workspace has been expired\n| DIS-LI-1011 | Service is not available to serve the request\n| DIS-LI-1014 | Batch size must not exceed 25\n| DIS-LI-1015 | Country is not provided in the request\n| DIS-LI-1016 | Not able to identify requested country\n| DIS-LI-1017 | Key type should be either PB_KEY, GNAF_PID, EIR_CODE, UPRN or UDPRN only\n| DIS-LI-1018 | Request Body is not valid\n| DIS-LI-1019 | Request body is not specified in the request\n| DIS-LI-1021 | Language: Requested Desired Language not supported in Requested Country\n| DIS-LI-1022 | Invalid desired alternate language code provided in custom preference\n| DIS-LI-1023 | Desired alternate language code is not provided in custom preference\n| DIS-LI-1025 | Type should be either POSTAL or CITY only\n| DIS-LI-1026 | Provided country is not supported for GNAF_PID\n| DIS-LI-1027 | Lookup key cannot be null or empty\n| DIS-LI-1028 | Invalid Transaction ID. It must be in the UUID format\n| DIS-LI-1029 | Unauthorized request access for data option\n| DIS-LI-1030 | Invalid data option in customPreferences\n| DIS-LI-1031 | Invalid label value in preferences\n| DIS-LI-1032 | Requested country is not supported\n| DIS-LI-1033 | Requested country is not supported for AddressBase data option\n| DIS-LI-1035 | You do not have permission to access requested country data\n| DIS-LI-1036 | Invalid value for maxResults\n| DIS-LI-1037 | CodeType is not provided in the request\n| DIS-LI-1038 | Invalid CodeType, it must be a valid codeType\n| DIS-LI-1039 | Code is null or blank\n| DIS-LI-1040 | Invalid code format for GlobalMatchCode in the request\n| DIS-LI-1041 | Invalid code format for GlobalLocationCode in the request\n| DIS-LI-1042 | Invalid code format for GlobalDeliveryIndicator in the request\n| DIS-LI-1043 | Invalid DATA_VERSION is provided in customPreferences. Please use the format yyyy-MM or specify LATEST\n| DIS-LI-1044 | Future vintage format option is provided in customPreferences\n| DIS-LI-1045 | Multi vintage is not supported for this region\n| DIS-LI-1046 | Requested country is not supported for the dataset\n
\n", "version": "1.0" }, "servers": [ { "url": "https://api.cloud.precisely.com" }, { "url": "https://api.eu1.cloud.precisely.com" }, { "url": "https://api.au1.cloud.precisely.com" }, { "url": "https://api.gb1.cloud.precisely.com" } ], "tags": [ { "name": "Address Autocomplete", "description": "Autocompletes the addresses." }, { "name": "Address Geocode", "description": "Geocodes the addresses" }, { "name": "ID Lookup", "description": "Finds the addresses using a unique identification ID" }, { "name": "Reverse Geocode", "description": "Reverse-geocode the addresses" }, { "name": "Address Verification", "description": "Performs address verification" }, { "name": "ExplainAddressCode", "description": "Turn cryptic address codes into clarity" }, { "name": "Address Proximity Search", "description": "Address proximity search using location" } ], "paths": { "/v1/autocomplete": { "post": { "tags": [ "Address Autocomplete" ], "summary": "Autocompletes the addresses.", "description": "This API autocompletes the addresses.The Address Autocomplete API when built into an application, will provide type-ahead capabilities. Only the first few characters of a place or address will yield match candidates. With additional typing, more specific information is revealed and the results are refined to display more relevant candidates.The Address Autocomplete API supports global coverage.", "operationId": "autocomplete", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "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.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "X-Transaction-Id", "in": "header", "description": "To handle a large number of calls and keep things organized, we group API calls for the same address into a single \"transaction.\"\n\nA transaction is considered complete when:\n\n- 15 seconds have passed, or\n- 12 API calls have been made, whichever happens first.\n\n**Transaction ID Behavior:**\n- The Transaction ID (GUID) must be sent as part of the `x-transaction-id` header in each API request.\n- We recommend users generate a new Transaction ID for every new transaction.\n- 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.\n\n**Examples:**\n\n**1. 15-Second Scenario:**\nA user starts typing an address and includes a Transaction ID (e.g., `1234-5678-ABCD`) in the `x-transaction-id` header:\n- They make 4 calls (e.g., for `\"12\"`, `\"123\"`, `\"123 Main\"`, `\"123 Main St\"`) within 15 seconds.\n- After 15 seconds, the transaction is marked complete.\n- 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`),\n our system will treat these additional calls as part of a new transaction.\n\n**2. 12-Call Scenario:**\nAnother user types quickly and includes a Transaction ID (e.g., `5678-1234-EFGH`) in the `x-transaction-id` header:\n- They make 12 calls (e.g., for `\"1\"`, `\"12\"`, `\"123\"`, ..., `\"123 Main St Apt 4\"`) within 3 seconds.\n- Since the 12-call limit is reached, the transaction is marked complete.\n- If the user continues to refine or add to their input using the same Transaction ID (`5678-1234-EFGH`),\n our system will treat these additional calls as part of a new transaction.\n", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "requestBody": { "description": "Autocomplete sample request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutocompleteRequest" }, "examples": { "example": { "value": { "preferences": { "maxResults": 2, "returnAllInfo": true, "factoryDescription": { "label": "", "featureSpecific": {} }, "clientLocale": "en_US", "clientCoordSysName": "", "distance": { "value": 150, "distanceUnit": "METER" }, "streetOffset": { "value": 7, "distanceUnit": "METER" }, "cornerOffset": { "value": 7, "distanceUnit": "METER" }, "fallbackToGeographic": true, "fallbackToPostal": true, "matchMode": "", "returnOfAdditionalFields": [], "originXY": [], "customPreferences": {} }, "address": { "addressLines": [ "350 Jordan" ], "country": "USA", "addressNumber": "", "admin1": "", "admin2": "", "city": "", "borough": "", "neighborhood": "", "suburb": "", "postalCode": "", "postalCodeExt": "", "placeName": "", "street": "", "building": "", "floor": "", "room": "", "unit": "", "unitType": "" } } } } } }, "required": true }, "responses": { "200": { "description": "Address predicted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutocompleteResponse" }, "examples": { "example": { "value": { "response": { "status": "OK", "predictions": [ { "prediction": "350 Jordan Ave, Montoursville PA 17754", "distance": { "value": 0, "distanceUnit": "METER" }, "address": { "formattedAddress": "350 Jordan Ave, Montoursville PA 17754", "formattedStreetAddress": "350 Jordan Ave", "formattedLocationAddress": "Montoursville, PA 17754", "addressNumber": "350", "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "PA", "shortName": "PA" }, "admin2": {}, "city": { "longName": "Montoursville", "shortName": "Montoursville" }, "neighborhood": {}, "postalCode": "17754", "street": "Jordan Ave" }, "addressLines": [ "350 Jordan Ave", "Montoursville PA 17754" ], "location": { "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -76.91419, 41.246719999999996 ] } } }, "explanation": { "addressMatch": { "description": [ { "label": "placeName", "matchType": "NONE" }, { "label": "addressNumber", "matchType": "EXACT", "matchedSubstring": "350" }, { "label": "admin1", "matchType": "NONE" }, { "label": "admin2", "matchType": "NONE" }, { "label": "city", "matchType": "NONE" }, { "label": "neighborhood", "matchType": "NONE" }, { "label": "suburb", "matchType": "NONE" }, { "label": "street", "matchType": "PARTIAL", "matchedSubstring": "JORDAN" }, { "label": "postalCode", "matchType": "NONE" }, { "label": "streetType", "matchType": "NONE" }, { "label": "postalCodeExt", "matchType": "NONE" }, { "label": "streetDirectional", "matchType": "NONE" } ] }, "source": { "label": "ggs" } }, "customFields": { "PB_KEY": "P0000JCAW989", "DISTANCE": "-0.0", "FROM_CUSTOM_DATASET": "false", "MATCHED_FROM_ADDRESSNUMBER": "350", "MATCHED_FROM_STREETNAME": "JORDAN", "ADDRESS_NUMBER_FROM": "350", "POSTAL_VERIFIED": "YES", "FORMATTED_STRING": "350 Jordan Ave, Montoursville, PA 17754", "RECORD_TYPE": "2", "FEATUREID": "102759609", "ZIP4": "2210", "DISTANCE_UNIT": "METERS" } }, { "prediction": "350 S Jordan Ave, San Jacinto CA 92583", "distance": { "value": 0, "distanceUnit": "METER" }, "address": { "formattedAddress": "350 S Jordan Ave, San Jacinto CA 92583", "formattedStreetAddress": "350 S Jordan Ave", "formattedLocationAddress": "San Jacinto, CA 92583", "addressNumber": "350", "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "CA", "shortName": "CA" }, "admin2": {}, "city": { "longName": "San Jacinto", "shortName": "San Jacinto" }, "neighborhood": {}, "postalCode": "92583", "street": "S Jordan Ave" }, "addressLines": [ "350 S Jordan Ave", "San Jacinto CA 92583" ], "location": { "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -116.95680999999999, 33.782465 ] } } }, "explanation": { "addressMatch": { "description": [ { "label": "placeName", "matchType": "NONE" }, { "label": "addressNumber", "matchType": "EXACT", "matchedSubstring": "350" }, { "label": "admin1", "matchType": "NONE" }, { "label": "admin2", "matchType": "NONE" }, { "label": "city", "matchType": "NONE" }, { "label": "neighborhood", "matchType": "NONE" }, { "label": "suburb", "matchType": "NONE" }, { "label": "street", "matchType": "PARTIAL", "matchedSubstring": "JORDAN" }, { "label": "postalCode", "matchType": "NONE" }, { "label": "streetType", "matchType": "NONE" }, { "label": "postalCodeExt", "matchType": "NONE" }, { "label": "streetDirectional", "matchType": "NONE" } ] }, "source": { "label": "ggs" } }, "customFields": { "PB_KEY": "P00002SZL9FS", "DISTANCE": "-0.0", "FROM_CUSTOM_DATASET": "false", "MATCHED_FROM_ADDRESSNUMBER": "350", "MATCHED_FROM_STREETNAME": "JORDAN", "ADDRESS_NUMBER_FROM": "350", "FORMATTED_STRING": "350 S Jordan Ave, San Jacinto, CA 92583", "RECORD_TYPE": "2", "FEATUREID": "106396168", "DISTANCE_UNIT": "METERS" } } ] } } } } } } }, "400": { "description": "Invalid request for Autocomplete API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Not able to identify ABC country (DIS-LI-1016)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Autocomplete API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Autocomplete API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Autocomplete API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal server error for Autocomplete API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } }, "503": { "description": "Autocomplete Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "SERVICE_UNAVAILABLE", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-LI-1011)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/autocomplete/postal-city": { "post": { "tags": [ "Address Autocomplete" ], "summary": "Provides intelligent suggestions for postal codes and city", "description": "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.\n\nThe 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.\n\nThis is an optional field. If it is not provided then the suggestions will be mix of postal code and city based.\n\nIt can have 2 values:\n- **POSTAL** : Suggestions will be based on postal codes only.\n\n- **CITY** : Suggestions will be based on city only.\n", "operationId": "autocompletePostalCity", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "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.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "requestBody": { "description": "Autocomplete postal-city sample request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutocompletePostalCityRequest" }, "examples": { "example": { "value": { "preferences": { "maxResults": 10, "returnAllInfo": true, "factoryDescription": { "label": "", "featureSpecific": {} }, "clientLocale": "en_US", "clientCoordSysName": "", "distance": { "value": 150, "distanceUnit": "METER" }, "streetOffset": { "value": 7, "distanceUnit": "METER" }, "cornerOffset": { "value": 7, "distanceUnit": "METER" }, "fallbackToGeographic": true, "fallbackToPostal": true, "matchMode": "", "returnOfAdditionalFields": [], "originXY": [], "customPreferences": {} }, "address": { "type": "POSTAL", "postAddress": "12180", "country": "USA" } } } } } }, "required": true }, "responses": { "200": { "description": "Address predicted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutocompletePostalCityResponse" }, "examples": { "example": { "value": { "response": { "status": "OK", "predictions": [ { "address": { "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "NY", "shortName": "NY" }, "admin2": { "longName": "Rensselaer", "shortName": "Rensselaer" }, "city": { "longName": "Troy", "shortName": "Troy" }, "postalCode": "12180" }, "location": { "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -73.66133, 42.73208 ] } } } }, { "address": { "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "NY", "shortName": "NY" }, "admin2": { "longName": "Rensselaer", "shortName": "Rensselaer" }, "city": { "longName": "Brunswick", "shortName": "Brunswick" }, "postalCode": "12180" }, "location": { "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -73.66133, 42.73208 ] } } } }, { "address": { "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "NY", "shortName": "NY" }, "admin2": { "longName": "Rensselaer", "shortName": "Rensselaer" }, "city": { "longName": "Wynantskill", "shortName": "Wynantskill" }, "postalCode": "12180" }, "location": { "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -73.66133, 42.73208 ] } } } }, { "address": { "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "NY", "shortName": "NY" }, "admin2": { "longName": "Rensselaer", "shortName": "Rensselaer" }, "city": { "longName": "North Greenbush", "shortName": "North Greenbush" }, "postalCode": "12180" }, "location": { "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -73.66133, 42.73208 ] } } } }, { "address": { "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "NY", "shortName": "NY" }, "admin2": { "longName": "Rensselaer", "shortName": "Rensselaer" }, "city": { "longName": "Grafton", "shortName": "Grafton" }, "postalCode": "12180" }, "location": { "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -73.66133, 42.73208 ] } } } }, { "address": { "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "NY", "shortName": "NY" }, "admin2": { "longName": "Rensselaer", "shortName": "Rensselaer" }, "city": { "longName": "Pittstown", "shortName": "Pittstown" }, "postalCode": "12180" }, "location": { "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -73.66133, 42.73208 ] } } } }, { "address": { "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "NY", "shortName": "NY" }, "admin2": { "longName": "Rensselaer", "shortName": "Rensselaer" }, "city": { "longName": "Poestenkill", "shortName": "Poestenkill" }, "postalCode": "12180" }, "location": { "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -73.66133, 42.73208 ] } } } } ] } } } } } } }, "400": { "description": "Invalid request for Autocomplete Postal City API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Not able to identify ABC country (DIS-LI-1016)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Autocomplete Postal City API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden fo rAutocomplete Postal City API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Autocomplete Postal City API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal server error fo Autocomplete Postal City API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } }, "503": { "description": "Autocomplete Postal City Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "SERVICE_UNAVAILABLE", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-LI-1011)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/explain-addresscode": { "post": { "tags": [ "ExplainAddressCode" ], "summary": "Explain Address Codes", "description": "Precisely ExplainAddressCode is an API that decodes proprietary Precisely address intelligence codes into structured, human-readable descriptions.\n\n**Supported code systems:**\n- Global Match Code (GMC)\n- Global Location Code (GLC)\n- Global Delivery Indicator (GDI)\n- Forward Result Code (FRC)\n- Reverse Result Code (RRC)\n\n**The API generates:**\n- Machine-readable structured fields\n- Human-friendly descriptions\n- Customizable insight summaries\n- Official Explain Codes\n- Supporting metadata\n", "operationId": "explainAddresscode", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "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.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "requestBody": { "description": "AddressCode request (supports GMC, GLC, GDI, FRC, RRC)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExplainAddressCodeRequest" }, "examples": { "GlobalMatchCode": { "summary": "GMC request", "value": { "codeType": "GlobalMatchCode", "codes": [ { "id": "1", "code": "V4-D0M0B0U4F0G0P4S4Q0X0A0T4E0R6W0Z4Y4C4-5" } ], "responseOptions": { "includeOfficialDescription": true } } }, "ForwardResultCode": { "summary": "FRC request", "value": { "codeType": "ForwardResultCode", "codes": [ { "id": "1", "code": "S8HPNTSCZA" } ], "responseOptions": { "includeOfficialDescription": true } } }, "ReverseResultCode": { "summary": "RRC request", "value": { "codeType": "ReverseResultCode", "codes": [ { "id": "1", "code": "RS8A" } ], "responseOptions": { "includeOfficialDescription": true } } } } } }, "required": true }, "responses": { "200": { "description": "All address codes explained successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExplainAddressCodeResponse" }, "examples": { "GlobalMatchCode": { "summary": "GMC success", "value": { "responses": [ { "id": "1", "status": "OK", "result": { "codeType": "GlobalMatchCode", "customerInsightSummary": "Address premise verified with high confidence. Region/State appended from reference data.", "officialDescription": { "addressMatchStatus": { "symbol": "V4", "status": "Verified", "verificationLevel": 4, "verificationLevelLabel": "Premise verified" }, "componentMatchStatus": { "A": { "label": "Sub-city", "value": 0, "meaning": "Not found or empty" }, "B": { "label": "Building", "value": 0, "meaning": "Not found or empty" }, "C": { "label": "Country", "value": 4, "meaning": "Verified without changes" }, "D": { "label": "Department", "value": 0, "meaning": "Not found or empty" }, "E": { "label": "Extra City", "value": 0, "meaning": "Not found or empty" }, "F": { "label": "Sub-premise2/Floor", "value": 0, "meaning": "Not found or empty" }, "G": { "label": "Sub-premise3/Room", "value": 0, "meaning": "Not found or empty" }, "M": { "label": "Company", "value": 0, "meaning": "Not found or empty" }, "P": { "label": "Premise/House Number", "value": 4, "meaning": "Verified without changes" }, "Q": { "label": "Sub-street", "value": 0, "meaning": "Not found or empty" }, "R": { "label": "Region/State", "value": 6, "meaning": "Appended using reference data" }, "S": { "label": "Street", "value": 4, "meaning": "Verified without changes" }, "T": { "label": "City", "value": 4, "meaning": "Verified without changes" }, "U": { "label": "Sub-premise/Unit", "value": 4, "meaning": "Verified without changes" }, "W": { "label": "Principality", "value": 0, "meaning": "Not found or empty" }, "X": { "label": "PO Box", "value": 0, "meaning": "Not found or empty" }, "Y": { "label": "Extra Postcode/Zip+4", "value": 4, "meaning": "Verified without changes" }, "Z": { "label": "Postcode/Zip Code", "value": 4, "meaning": "Verified without changes" } }, "matchConfidence": { "value": 5, "label": "High Confidence" } } } } ], "documentationLink": "https://help.cloud.precisely.com/r/t/1737727574924/2025-11-18/Precisely-Data-Integrity-Suite/disapi/Latest/en-US/Data-Integrity-Suite-APIs/Global-Match-Code", "generatedAt": "2025-12-11T07:03:12.392709800Z" } }, "ForwardResultCode": { "summary": "FRC success", "value": { "responses": [ { "id": "1", "status": "OK", "result": { "codeType": "ForwardResultCode", "customerInsightSummary": "Precise address-point (rooftop) match with full component agreement across house number, street, city, and postal code.", "officialDescription": { "code": "S8HPNTSCZA", "matchType": "Street", "accuracy": { "level": "8", "label": "Exact address point", "customerInsight": "Precise address-point (rooftop) match." }, "components": [ { "flag": "H", "description": "House number match", "matched": true }, { "flag": "P", "description": "Street prefix match", "matched": true }, { "flag": "N", "description": "Street name match", "matched": true }, { "flag": "T", "description": "Street type match", "matched": true }, { "flag": "S", "description": "Street suffix match", "matched": true }, { "flag": "C", "description": "City/Town match", "matched": true }, { "flag": "Z", "description": "Postal code match", "matched": true }, { "flag": "A", "description": "Address Dictionary match", "matched": true } ] } } } ], "documentationLink": "https://docs.precisely.com/docs/sftw/ggs/5.0/en/webhelp/GeoAddressingSDKDeveloperGuide/GlobalGeocodingGuide/source/ResultCodes/Intl_Geocoding/forward_geocoding_codes_2.html", "generatedAt": "2026-03-18T10:15:30.000000000Z" } }, "ReverseResultCode": { "summary": "RRC success", "value": { "responses": [ { "id": "1", "status": "OK", "result": { "codeType": "ReverseResultCode", "customerInsightSummary": "High confidence match to building or parcel centroid with accurate reference data.", "officialDescription": { "code": "RS8A", "matchType": "Street", "precision": { "level": "8", "label": "Building/Parcel", "customerInsight": "Match to building or parcel centroid", "accuracyRange": "10-25 meters" }, "quality": { "grade": "A", "label": "High Quality", "customerInsight": "High confidence match with accurate reference data", "confidence": "95-100%" } } } } ], "documentationLink": "https://docs.precisely.com/docs/sftw/ggs/5.0/en/webhelp/GeoAddressingSDKDeveloperGuide/GlobalGeocodingGuide/source/ResultCodes/Intl_Geocoding/reverse_geocoding_codes_2.html", "generatedAt": "2026-03-18T10:20:00.000000000Z" } } } } } }, "206": { "description": "Address codes explained partially (some failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExplainAddressCodeResponse" }, "examples": { "GlobalMatchCode": { "summary": "GMC partial", "value": { "responses": [ { "id": "1", "status": "OK", "result": { "codeType": "GlobalMatchCode", "customerInsightSummary": "Address premise verified with high confidence. Region/State appended from reference data.", "officialDescription": { "addressMatchStatus": { "symbol": "V4", "status": "Verified", "verificationLevel": 4, "verificationLevelLabel": "Premise verified" }, "componentMatchStatus": { "A": { "label": "Sub-city", "value": 0, "meaning": "Not found or empty" }, "B": { "label": "Building", "value": 0, "meaning": "Not found or empty" }, "C": { "label": "Country", "value": 4, "meaning": "Verified without changes" }, "D": { "label": "Department", "value": 0, "meaning": "Not found or empty" }, "E": { "label": "Extra City", "value": 0, "meaning": "Not found or empty" }, "F": { "label": "Sub-premise2/Floor", "value": 0, "meaning": "Not found or empty" }, "G": { "label": "Sub-premise3/Room", "value": 0, "meaning": "Not found or empty" }, "M": { "label": "Company", "value": 0, "meaning": "Not found or empty" }, "P": { "label": "Premise/House Number", "value": 4, "meaning": "Verified without changes" }, "Q": { "label": "Sub-street", "value": 0, "meaning": "Not found or empty" }, "R": { "label": "Region/State", "value": 6, "meaning": "Appended using reference data" }, "S": { "label": "Street", "value": 4, "meaning": "Verified without changes" }, "T": { "label": "City", "value": 4, "meaning": "Verified without changes" }, "U": { "label": "Sub-premise/Unit", "value": 4, "meaning": "Verified without changes" }, "W": { "label": "Principality", "value": 0, "meaning": "Not found or empty" }, "X": { "label": "PO Box", "value": 0, "meaning": "Not found or empty" }, "Y": { "label": "Extra Postcode/Zip+4", "value": 4, "meaning": "Verified without changes" }, "Z": { "label": "Postcode/Zip Code", "value": 4, "meaning": "Verified without changes" } }, "matchConfidence": { "value": 5, "label": "High Confidence" } } } }, { "id": "2", "status": "INVALID_REQUEST", "errorMessage": "Invalid code format for GlobalMatchCode in the request (DIS-LI-1040): code too short" } ], "documentationLink": "https://help.cloud.precisely.com/r/t/1737727574924/2025-11-18/Precisely-Data-Integrity-Suite/disapi/Latest/en-US/Data-Integrity-Suite-APIs/Global-Match-Code", "generatedAt": "2025-12-11T07:04:17.751280300Z" } }, "ForwardResultCode": { "summary": "FRC partial", "value": { "responses": [ { "id": "1", "status": "OK", "result": { "codeType": "ForwardResultCode", "customerInsightSummary": "Matched at city/town level.", "officialDescription": { "code": "G3", "matchType": "Geographic", "accuracy": { "level": "3", "label": "City/Town centroid", "customerInsight": "Matched at city/town level." } } } }, { "id": "2", "status": "INVALID_REQUEST", "errorMessage": "Invalid code format for ForwardResultCode in the request (DIS-LI-1050): code too short" } ], "documentationLink": "https://docs.precisely.com/docs/sftw/ggs/5.0/en/webhelp/GeoAddressingSDKDeveloperGuide/GlobalGeocodingGuide/source/ResultCodes/Intl_Geocoding/forward_geocoding_codes_2.html", "generatedAt": "2026-03-18T10:16:45.000000000Z" } }, "ReverseResultCode": { "summary": "RRC partial", "value": { "responses": [ { "id": "1", "status": "OK", "result": { "codeType": "ReverseResultCode", "customerInsightSummary": "Matched to city or town administrative boundary.", "officialDescription": { "code": "RG3", "matchType": "Geographic", "precision": { "level": "3", "label": "City/Town", "customerInsight": "Matched to city or town administrative boundary", "accuracyRange": "0.5-5 km" } } } }, { "id": "2", "status": "INVALID_REQUEST", "errorMessage": "Invalid code format for ReverseResultCode in the request (DIS-LI-1060): code too short" } ], "documentationLink": "https://docs.precisely.com/docs/sftw/ggs/5.0/en/webhelp/GeoAddressingSDKDeveloperGuide/GlobalGeocodingGuide/source/ResultCodes/Intl_Geocoding/reverse_geocoding_codes_2.html", "generatedAt": "2026-03-18T10:21:15.000000000Z" } } } } } }, "400": { "description": "Invalid request - bad codeType, batch size exceeded, or all codes failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "GlobalMatchCode": { "summary": "GMC bad request", "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Invalid code format for GlobalMatchCode in the request (DIS-LI-1040): component order violation - Company (M) must come before Sub-premise/Unit (U)" } ] } }, "ForwardResultCode": { "summary": "FRC bad request", "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Invalid code format for ForwardResultCode in the request (DIS-LI-1050): code too short" } ] } }, "ReverseResultCode": { "summary": "RRC bad request", "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Invalid code format for ReverseResultCode in the request (DIS-LI-1060): code too short" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "413": { "description": "Request entity too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "BATCH_SIZE_EXCEEDED", "errorMessage": "Batch size must not exceed 25 (DIS-LI-1014)" } ] } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "SERVICE_UNAVAILABLE", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-LI-1011)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/express-autocomplete": { "post": { "tags": [ "Address Autocomplete Express" ], "summary": "Enhances address autocompletion", "description": "\nThis 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.\n\nThe 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.\n\nList of supported countries for Address Autocomplete Express API with applicable **SEARCH_TYPE**:\n\n| SEARCH_TYPE | COUNTRY |\n|-------------|-------------|\n| 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) |\n| 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) |\n| POI | USA, CAN, GBR, CHN, JPN, HKG, THA, TWN, EGY, RUS, COL, AUS |\n\nNote: This API is only available in US region.\n", "operationId": "autocompleteV2", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "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.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "X-Transaction-Id", "in": "header", "description": "To handle a large number of calls and keep things organized, we group API calls for the same address into a single \"transaction.\"\n\nA transaction is considered complete when:\n\n- 15 seconds have passed, or\n- 12 API calls have been made, whichever happens first.\n\n**Transaction ID Behavior:**\n- The Transaction ID (GUID) must be sent as part of the `x-transaction-id` header in each API request.\n- We recommend users generate a new Transaction ID for every new transaction.\n- 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.\n\n**Examples:**\n\n**1. 15-Second Scenario:**\nA user starts typing an address and includes a Transaction ID (e.g., `1234-5678-ABCD`) in the `x-transaction-id` header:\n- They make 4 calls (e.g., for `\"12\"`, `\"123\"`, `\"123 Main\"`, `\"123 Main St\"`) within 15 seconds.\n- After 15 seconds, the transaction is marked complete.\n- 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`),\n our system will treat these additional calls as part of a new transaction.\n\n**2. 12-Call Scenario:**\nAnother user types quickly and includes a Transaction ID (e.g., `5678-1234-EFGH`) in the `x-transaction-id` header:\n- They make 12 calls (e.g., for `\"1\"`, `\"12\"`, `\"123\"`, ..., `\"123 Main St Apt 4\"`) within 3 seconds.\n- Since the 12-call limit is reached, the transaction is marked complete.\n- If the user continues to refine or add to their input using the same Transaction ID (`5678-1234-EFGH`),\n our system will treat these additional calls as part of a new transaction.\n", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "requestBody": { "description": "Autocomplete express sample request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutocompleteRequest" }, "examples": { "example": { "value": { "preferences": { "maxResults": 5, "returnAllInfo": true, "factoryDescription": { "label": "", "featureSpecific": {} }, "clientLocale": "en_US", "clientCoordSysName": "", "distance": { "value": 150, "distanceUnit": "METER" }, "streetOffset": { "value": 7, "distanceUnit": "METER" }, "cornerOffset": { "value": 7, "distanceUnit": "METER" }, "fallbackToGeographic": true, "fallbackToPostal": true, "matchMode": "", "returnOfAdditionalFields": [], "originXY": [], "customPreferences": { "SEARCH_TYPE": "ADDRESS" } }, "address": { "addressLines": [ "350 Jordan" ], "country": "USA", "addressNumber": "", "admin1": "", "admin2": "", "city": "", "borough": "", "neighborhood": "", "suburb": "", "postalCode": "", "postalCodeExt": "", "placeName": "", "street": "", "building": "", "floor": "", "room": "", "unit": "", "unitType": "" } } } } } }, "required": true }, "responses": { "200": { "description": "Address predicted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutocompleteResponse" }, "examples": { "example": { "value": { "response": { "status": "OK", "predictions": [ { "prediction": "350 Jordan Ave, Montoursville PA 17754-2210", "address": { "formattedAddress": "350 Jordan Ave, Montoursville PA 17754-2210", "formattedStreetAddress": "350 Jordan Ave", "formattedLocationAddress": "Montoursville PA 17754-2210", "addressNumber": "350", "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "PA", "shortName": "PA" }, "city": { "longName": "Montoursville", "shortName": "Montoursville" }, "postalCode": "17754", "postalCodeExt": "2210", "street": "Jordan Ave" }, "addressLines": [ "350 Jordan Ave", "Montoursville PA 17754-2210" ], "customFields": { "PB_KEY": "P0000JCAW989" } }, { "prediction": "350 Jordan Dr, Clayton DE 19938-2414", "address": { "formattedAddress": "350 Jordan Dr, Clayton DE 19938-2414", "formattedStreetAddress": "350 Jordan Dr", "formattedLocationAddress": "Clayton DE 19938-2414", "addressNumber": "350", "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "DE", "shortName": "DE" }, "city": { "longName": "Clayton", "shortName": "Clayton" }, "postalCode": "19938", "postalCodeExt": "2414", "street": "Jordan Dr" }, "addressLines": [ "350 Jordan Dr", "Clayton DE 19938-2414" ], "customFields": { "PB_KEY": "P00004N1G1NF" } }, { "prediction": "350 Jordan St, Shreveport LA 71101-4847", "address": { "formattedAddress": "350 Jordan St, Shreveport LA 71101-4847", "formattedStreetAddress": "350 Jordan St", "formattedLocationAddress": "Shreveport LA 71101-4847", "addressNumber": "350", "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "LA", "shortName": "LA" }, "city": { "longName": "Shreveport", "shortName": "Shreveport" }, "postalCode": "71101", "postalCodeExt": "4847", "street": "Jordan St" }, "addressLines": [ "350 Jordan St", "Shreveport LA 71101-4847" ], "customFields": { "PB_KEY": "P0000A5IQA2A" } }, { "prediction": "350 Jordan Rd, Sedona AZ 86336-4830", "address": { "formattedAddress": "350 Jordan Rd, Sedona AZ 86336-4830", "formattedStreetAddress": "350 Jordan Rd", "formattedLocationAddress": "Sedona AZ 86336-4830", "addressNumber": "350", "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "AZ", "shortName": "AZ" }, "city": { "longName": "Sedona", "shortName": "Sedona" }, "postalCode": "86336", "postalCodeExt": "4830", "street": "Jordan Rd" }, "addressLines": [ "350 Jordan Rd", "Sedona AZ 86336-4830" ], "customFields": { "PB_KEY": "P00001VUMITN" } }, { "prediction": "350 Jordan Cir, Louisville MS 39339-3476", "address": { "formattedAddress": "350 Jordan Cir, Louisville MS 39339-3476", "formattedStreetAddress": "350 Jordan Cir", "formattedLocationAddress": "Louisville MS 39339-3476", "addressNumber": "350", "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "MS", "shortName": "MS" }, "city": { "longName": "Louisville", "shortName": "Louisville" }, "postalCode": "39339", "postalCodeExt": "3476", "street": "Jordan Cir" }, "addressLines": [ "350 Jordan Cir", "Louisville MS 39339-3476" ], "customFields": { "PB_KEY": "P0000CX3494O" } } ] } } } } } } }, "400": { "description": "Invalid request for Autocomplete Express API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Not able to identify ABC country (DIS-LI-1016)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Autocomplete Express API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Autocomplete Express API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Autocomplete Express API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal server error for Autocomplete Express API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } }, "503": { "description": "Autocomplete Express Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "SERVICE_UNAVAILABLE", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-LI-1011)" } ] } } } } } } }, "deprecated": true, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/geocode": { "post": { "tags": [ "Address Geocode" ], "summary": "Geocodes the addresses", "description": "\nThis API geocodes the addresses. It takes a single input address or multiple input addresses and returns standardized US or international address and geocoding information. The Address Geocode API supports global coverage.\n\nThe Gecode API also supports Custom Preferences. These preferences are for use with any country dataset.\nFor more details on these preferences see Custom Preferences\n", "operationId": "geocode", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "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.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "requestBody": { "description": "Geocode sample request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeRequest" }, "examples": { "example": { "value": { "preferences": { "maxResults": 1, "returnAllInfo": true, "factoryDescription": { "label": "", "featureSpecific": {} }, "clientLocale": "en_US", "clientCoordSysName": "", "distance": { "value": 150, "distanceUnit": "METER" }, "streetOffset": { "value": 7, "distanceUnit": "METER" }, "cornerOffset": { "value": 7, "distanceUnit": "METER" }, "fallbackToGeographic": true, "fallbackToPostal": true, "matchMode": "", "returnOfAdditionalFields": [], "originXY": [], "customPreferences": {} }, "addresses": [ { "addressId": "1", "addressLines": [ "1700 District Ave #300 Burlington, MA" ], "country": "USA", "addressNumber": "", "admin1": "", "admin2": "", "city": "", "borough": "", "neighborhood": "", "suburb": "", "postalCode": "", "postalCodeExt": "", "placeName": "", "street": "", "building": "", "floor": "", "room": "", "unit": "", "unitType": "" } ] } } } } }, "required": true }, "responses": { "200": { "description": "Address(es) geocoded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeResponse" }, "examples": { "example": { "value": { "responses": [ { "addressId": "1", "status": "OK", "results": [ { "score": 97, "address": { "formattedAddress": "1700 DISTRICT AVE STE 300, BURLINGTON MA 01803-5231, United States", "formattedStreetAddress": "1700 DISTRICT AVE STE 300", "formattedLocationAddress": "BURLINGTON, MA 01803-5231", "unitType": "STE", "addressNumber": "1700", "country": { "name": "United States", "isoAlpha2Code": "US", "isoAlpha3Code": "USA", "isoNumericCode": "840" }, "admin1": { "longName": "Massachusetts", "shortName": "MA" }, "admin2": { "longName": "MIDDLESEX COUNTY", "shortName": "MIDDLESEX COUNTY" }, "city": { "longName": "BURLINGTON", "shortName": "BURLINGTON" }, "postalCode": "01803", "postalCodeExt": "5231", "street": "DISTRICT", "unit": "300" }, "addressLines": [ "1700 DISTRICT AVE STE 300", "BURLINGTON MA 01803-5231", "United States" ], "location": { "explanation": { "type": "ADDRESS_POINT", "description": "BUILDING", "designation": "CENTROID" }, "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -71.207799, 42.483939 ] } } }, "explanation": { "addressMatch": { "type": "ADDRESS", "description": [ { "label": "placeName", "matchType": "NONE" }, { "label": "addressNumber", "matchType": "EXACT" }, { "label": "admin1", "matchType": "EXACT" }, { "label": "admin2", "matchType": "NONE" }, { "label": "city", "matchType": "EXACT" }, { "label": "neighborhood", "matchType": "NONE" }, { "label": "suburb", "matchType": "NONE" }, { "label": "street", "matchType": "EXACT" }, { "label": "postalCode", "matchType": "NONE" }, { "label": "streetType", "matchType": "EXACT" }, { "label": "postalCodeExt", "matchType": "NONE" }, { "label": "streetDirectional", "matchType": "EXACT" }, { "label": "unitMatch", "matchType": "NONE" } ] }, "source": { "label": "ggs" } }, "customFields": { "RESBUS": "B", "POBOX_ZONE": "N", "LOTSIZE_METERS": "14677", "CSA_NUMBER": "148", "TYPE_SHORT": "AVE", "THOROUGHFARE_TYPE": "AVE", "HIUNIT": "300", "PARCEN_ELEVATION_METERS": "42.4", "ROAD_CLASS": "01", "MATCH_CODE": "S902", "COUNTY": "25017", "PB_KEY": "P0000BJ4F90Q", "LANGUAGE": "en", "UNIT_TYPE": "STE", "ADDRTYPE": "M", "INC_IND": "N", "BLOCK_2010": "250173324002012", "NON_DELIVERABLE": "N", "POINT_ID": "100893034", "CHECK_DIGIT": "5", "METRO_FLAG": "Y", "BLOCK": "250173324011003", "POST_THOROUGHFARE_TYPE": "AVE", "QCITY": "250065000", "ZIP_FACILITY": "P", "TFID": "258319428", "UNIT_RANGE_PARITY": "E", "APN_ID": "BURL M:000046 P:000051", "LOT_CODE": "A", "LOT_NUM": "0188", "GEOHASH": "drt3etunfh0x", "CTYST_KEY": "V21569", "UACEPOP": "4382009", "NAME": "DISTRICT", "ZIP_CARRTSORT": "D", "PARENT_ID": "P0000BJ68DL3", "LORANGE": "1700", "CLOSE_MATCH": "T", "ZIP_VALID": "Y", "STREET_SIDE": "L", "DATATYPE": "12", "INTERSECTION": "F", "ZIP_CITY_DELV": "Y", "LOUNIT": "300", "LOC_CODE": "AP05", "GLOBAL_LOCATION_CODE": "662", "CART": "C023", "NAME_CITY": "BURLINGTON", "BLOCK_LEFT": "250173324011003", "COUNTY_FIPS": "25017", "PRECISION_LEVEL": "19", "HIRANGE": "1700", "UACE": "09271", "REC_TYPE": "H", "HI_RISE_DFLT": "N", "URBANICITY": "L", "RESOLVED_LINE": "0", "MATCH_TYPE": "ADDRESS", "PARCEN_ELEVATION": "139", "PREF_CITY": "BURLINGTON", "CBSA_NUMBER": "14460", "ALT_FLAG": "B", "SEGMENT_DIRECTION": "F", "ADDRLINE_SHORT": "1700 DISTRICT AVE STE 300", "LOTSIZE": "157983", "CONFIDENCE": "89", "HIZIP4": "5231", "DATATYPE_NAME": "MASTER LOCATION", "ORIG_DPBC": "75", "SEGMENT_PARITY": "R", "CBSA_DIVISION_NAME": "CAMBRIDGE-NEWTON-FRAMINGHAM, MA METROPOLITAN DIVISION", "LOZIP4": "5231", "CSA_NAME": "BOSTON-WORCESTER-PROVIDENCE, MA-RI-NH COMBINED STATISTICAL AREA", "DPBC": "75", "LASTLINE_SHORT": "BURLINGTON, MA 01803-5231", "PLACE": "2509875", "CITY_SHORT": "BURLINGTON", "NAME_SHORT": "DISTRICT", "ZIP9": "018035231", "IS_ALIAS": "N01", "PRECISION_CODE": "S8HPNTSC-A", "ZIP10": "01803-5231", "CBSA_NAME": "BOSTON-CAMBRIDGE-NEWTON, MA-NH METROPOLITAN STATISTICAL AREA", "RANGE_PARITY": "E", "CBSA_DIVISION_NUMBER": "15764" } } ] } ] } } } } } }, "206": { "description": "Address(es) geocoded partially", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeResponse" }, "examples": { "example": { "value": { "responses": [ { "addressId": "1", "errorMessage": "Not able to identify ABC country (DIS-LI-1016)", "status": "INVALID_REQUEST" }, { "addressId": "2", "status": "OK", "results": [ { "score": 97, "address": { "formattedAddress": "1700 DISTRICT AVE STE 300, BURLINGTON MA 01803-5231, United States", "formattedStreetAddress": "1700 DISTRICT AVE STE 300", "formattedLocationAddress": "BURLINGTON, MA 01803-5231", "unitType": "STE", "addressNumber": "1700", "country": { "name": "United States", "isoAlpha2Code": "US", "isoAlpha3Code": "USA", "isoNumericCode": "840" }, "admin1": { "longName": "Massachusetts", "shortName": "MA" }, "admin2": { "longName": "MIDDLESEX COUNTY", "shortName": "MIDDLESEX COUNTY" }, "city": { "longName": "BURLINGTON", "shortName": "BURLINGTON" }, "postalCode": "01803", "postalCodeExt": "5231", "street": "DISTRICT", "unit": "300" }, "addressLines": [ "1700 DISTRICT AVE STE 300", "BURLINGTON MA 01803-5231", "United States" ], "location": { "explanation": { "type": "ADDRESS_POINT", "description": "BUILDING", "designation": "CENTROID" }, "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -71.207799, 42.483939 ] } } }, "explanation": { "addressMatch": { "type": "ADDRESS", "description": [ { "label": "placeName", "matchType": "NONE" }, { "label": "addressNumber", "matchType": "EXACT" }, { "label": "admin1", "matchType": "EXACT" }, { "label": "admin2", "matchType": "NONE" }, { "label": "city", "matchType": "EXACT" }, { "label": "neighborhood", "matchType": "NONE" }, { "label": "suburb", "matchType": "NONE" }, { "label": "street", "matchType": "EXACT" }, { "label": "postalCode", "matchType": "NONE" }, { "label": "streetType", "matchType": "EXACT" }, { "label": "postalCodeExt", "matchType": "NONE" }, { "label": "streetDirectional", "matchType": "EXACT" }, { "label": "unitMatch", "matchType": "NONE" } ] }, "source": { "label": "ggs" } }, "customFields": { "RESBUS": "B", "POBOX_ZONE": "N", "LOTSIZE_METERS": "14677", "CSA_NUMBER": "148", "TYPE_SHORT": "AVE", "THOROUGHFARE_TYPE": "AVE", "HIUNIT": "300", "PARCEN_ELEVATION_METERS": "42.4", "ROAD_CLASS": "01", "MATCH_CODE": "S902", "COUNTY": "25017", "PB_KEY": "P0000BJ4F90Q", "LANGUAGE": "en", "UNIT_TYPE": "STE", "ADDRTYPE": "M", "INC_IND": "N", "BLOCK_2010": "250173324002012", "NON_DELIVERABLE": "N", "POINT_ID": "100893034", "CHECK_DIGIT": "5", "METRO_FLAG": "Y", "BLOCK": "250173324011003", "POST_THOROUGHFARE_TYPE": "AVE", "QCITY": "250065000", "ZIP_FACILITY": "P", "TFID": "258319428", "UNIT_RANGE_PARITY": "E", "APN_ID": "BURL M:000046 P:000051", "LOT_CODE": "A", "LOT_NUM": "0188", "GEOHASH": "drt3etunfh0x", "CTYST_KEY": "V21569", "UACEPOP": "4382009", "NAME": "DISTRICT", "ZIP_CARRTSORT": "D", "PARENT_ID": "P0000BJ68DL3", "LORANGE": "1700", "CLOSE_MATCH": "T", "ZIP_VALID": "Y", "STREET_SIDE": "L", "DATATYPE": "12", "INTERSECTION": "F", "ZIP_CITY_DELV": "Y", "LOUNIT": "300", "LOC_CODE": "AP05", "GLOBAL_LOCATION_CODE": "662", "CART": "C023", "NAME_CITY": "BURLINGTON", "BLOCK_LEFT": "250173324011003", "COUNTY_FIPS": "25017", "PRECISION_LEVEL": "19", "HIRANGE": "1700", "UACE": "09271", "REC_TYPE": "H", "HI_RISE_DFLT": "N", "URBANICITY": "L", "RESOLVED_LINE": "0", "MATCH_TYPE": "ADDRESS", "PARCEN_ELEVATION": "139", "PREF_CITY": "BURLINGTON", "CBSA_NUMBER": "14460", "ALT_FLAG": "B", "SEGMENT_DIRECTION": "F", "ADDRLINE_SHORT": "1700 DISTRICT AVE STE 300", "LOTSIZE": "157983", "CONFIDENCE": "89", "HIZIP4": "5231", "DATATYPE_NAME": "MASTER LOCATION", "ORIG_DPBC": "75", "SEGMENT_PARITY": "R", "CBSA_DIVISION_NAME": "CAMBRIDGE-NEWTON-FRAMINGHAM, MA METROPOLITAN DIVISION", "LOZIP4": "5231", "CSA_NAME": "BOSTON-WORCESTER-PROVIDENCE, MA-RI-NH COMBINED STATISTICAL AREA", "DPBC": "75", "LASTLINE_SHORT": "BURLINGTON, MA 01803-5231", "PLACE": "2509875", "CITY_SHORT": "BURLINGTON", "NAME_SHORT": "DISTRICT", "ZIP9": "018035231", "IS_ALIAS": "N01", "PRECISION_CODE": "S8HPNTSC-A", "ZIP10": "01803-5231", "CBSA_NAME": "BOSTON-CAMBRIDGE-NEWTON, MA-NH METROPOLITAN STATISTICAL AREA", "RANGE_PARITY": "E", "CBSA_DIVISION_NUMBER": "15764" } } ] } ] } } } } } }, "400": { "description": "Invalid request for Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Not able to identify ABC country (DIS-LI-1016)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "413": { "description": "Request entity too large for Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "BATCH_SIZE_EXCEEDED", "errorMessage": "Batch size must not exceed 25 (DIS-LI-1014)" } ] } } } } } }, "429": { "description": "Too many requests for Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal server error for Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "SERVICE_UNAVAILABLE", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-LI-1011)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/lookup": { "post": { "tags": [ "ID Lookup" ], "summary": "Finds the addresses using a unique identification ID", "description": "\nThis 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.\n\n**Note**: Currently, no preferences are honored for this ID Lookup API.\n", "operationId": "lookup", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "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.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "requestBody": { "description": "ID lookup sample request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupRequest" }, "examples": { "example": { "value": { "preferences": { "maxResults": 1, "returnAllInfo": true, "factoryDescription": { "label": "", "featureSpecific": {} }, "clientLocale": "en_US", "clientCoordSysName": "", "distance": { "value": 150, "distanceUnit": "METER" }, "streetOffset": { "value": 7, "distanceUnit": "METER" }, "cornerOffset": { "value": 7, "distanceUnit": "METER" }, "fallbackToGeographic": true, "fallbackToPostal": true, "matchMode": "", "returnOfAdditionalFields": [], "originXY": [], "customPreferences": {} }, "keys": [ { "key": "P0000GL41OME", "country": "USA", "type": "PB_KEY" } ] } } } } }, "required": true }, "responses": { "200": { "description": "ID lookup successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupResponse" }, "examples": { "example": { "value": { "responses": [ { "status": "OK", "results": [ { "score": 0, "address": { "formattedAddress": "1 GLOBAL VW, TROY NY 12180-8371, United States", "formattedStreetAddress": "1 GLOBAL VW", "formattedLocationAddress": "TROY, NY 12180-8371", "addressNumber": "1", "country": { "name": "United States", "isoAlpha2Code": "US", "isoAlpha3Code": "USA", "isoNumericCode": "840" }, "admin1": { "longName": "New York", "shortName": "NY" }, "admin2": { "longName": "RENSSELAER COUNTY", "shortName": "RENSSELAER COUNTY" }, "city": { "longName": "TROY", "shortName": "TROY" }, "postalCode": "12180", "postalCodeExt": "8371", "street": "GLOBAL" }, "addressLines": [ "1 GLOBAL VW", "TROY NY 12180-8371", "United States" ], "location": { "explanation": { "type": "ADDRESS_POINT", "description": "BUILDING", "designation": "CENTROID" }, "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -73.704443, 42.682242 ] } } }, "explanation": { "addressMatch": { "description": [ { "label": "placeName", "matchType": "NONE" }, { "label": "addressNumber", "matchType": "NONE" }, { "label": "admin1", "matchType": "EXACT" }, { "label": "admin2", "matchType": "NONE" }, { "label": "city", "matchType": "EXACT" }, { "label": "neighborhood", "matchType": "NONE" }, { "label": "suburb", "matchType": "NONE" }, { "label": "street", "matchType": "EXACT" }, { "label": "postalCode", "matchType": "EXACT" }, { "label": "streetType", "matchType": "EXACT" }, { "label": "postalCodeExt", "matchType": "EXACT" }, { "label": "streetDirectional", "matchType": "EXACT" }, { "label": "unitMatch", "matchType": "EXACT" } ] }, "source": { "label": "ggs" } }, "customFields": { "POBOX_ZONE": "N", "CSA_NUMBER": "104", "TYPE_SHORT": "VW", "THOROUGHFARE_TYPE": "VW", "ROAD_CLASS": "01", "MATCH_CODE": "V000", "COUNTY": "36083", "PB_KEY": "P0000GL41OME", "LANGUAGE": "en", "NON_DELIVERABLE": "N", "POINT_ID": "105104102", "CHECK_DIGIT": "8", "METRO_FLAG": "Y", "BLOCK": "360830523011008", "POST_THOROUGHFARE_TYPE": "VW", "QCITY": "361297000", "ZIP_FACILITY": "P", "LOT_CODE": "A", "LOT_NUM": "0052", "GEOHASH": "dredff441fxf", "CTYST_KEY": "V16572", "NAME": "GLOBAL", "ZIP_CARRTSORT": "D", "LORANGE": "1", "CLOSE_MATCH": "T", "ZIP_VALID": "Y", "STREET_SIDE": "L", "DATATYPE": "12", "INTERSECTION": "F", "ZIP_CITY_DELV": "Y", "LOC_CODE": "AP05", "GLOBAL_LOCATION_CODE": "662", "CART": "C099", "NAME_CITY": "TROY", "BLOCK_LEFT": "360830523011008", "COUNTY_FIPS": "36083", "PRECISION_LEVEL": "19", "HIRANGE": "1", "REC_TYPE": "S", "RESOLVED_LINE": "0", "PREF_CITY": "TROY", "CBSA_NUMBER": "10580", "ALT_FLAG": "B", "SEGMENT_DIRECTION": "F", "ADDRLINE_SHORT": "1 GLOBAL VW", "CONFIDENCE": "96", "HIZIP4": "8371", "DATATYPE_NAME": "MASTER LOCATION", "ORIG_DPBC": "01", "SEGMENT_PARITY": "L", "LOZIP4": "8371", "CSA_NAME": "ALBANY-SCHENECTADY, NY COMBINED STATISTICAL AREA", "DPBC": "01", "LASTLINE_SHORT": "TROY, NY 12180-8371", "CITY_SHORT": "TROY", "NAME_SHORT": "GLOBAL", "ZIP9": "121808371", "IS_ALIAS": "N01", "PRECISION_CODE": "S8H------A", "ZIP10": "12180-8371", "CBSA_NAME": "ALBANY-SCHENECTADY-TROY, NY METROPOLITAN STATISTICAL AREA", "RANGE_PARITY": "O" } } ] } ] } } } } } }, "206": { "description": "ID lookup partially", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupResponse" }, "examples": { "example": { "value": { "responses": [ { "errorMessage": "Not able to identify ABC country (DIS-LI-1016)", "status": "INVALID_REQUEST" }, { "status": "OK", "results": [ { "score": 0, "address": { "formattedAddress": "1 GLOBAL VW, TROY NY 12180-8371, United States", "formattedStreetAddress": "1 GLOBAL VW", "formattedLocationAddress": "TROY, NY 12180-8371", "addressNumber": "1", "country": { "name": "United States", "isoAlpha2Code": "US", "isoAlpha3Code": "USA", "isoNumericCode": "840" }, "admin1": { "longName": "New York", "shortName": "NY" }, "admin2": { "longName": "RENSSELAER COUNTY", "shortName": "RENSSELAER COUNTY" }, "city": { "longName": "TROY", "shortName": "TROY" }, "postalCode": "12180", "postalCodeExt": "8371", "street": "GLOBAL" }, "addressLines": [ "1 GLOBAL VW", "TROY NY 12180-8371", "United States" ], "location": { "explanation": { "type": "ADDRESS_POINT", "description": "BUILDING", "designation": "CENTROID" }, "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -73.704443, 42.682242 ] } } }, "explanation": { "addressMatch": { "description": [ { "label": "placeName", "matchType": "NONE" }, { "label": "addressNumber", "matchType": "NONE" }, { "label": "admin1", "matchType": "EXACT" }, { "label": "admin2", "matchType": "NONE" }, { "label": "city", "matchType": "EXACT" }, { "label": "neighborhood", "matchType": "NONE" }, { "label": "suburb", "matchType": "NONE" }, { "label": "street", "matchType": "EXACT" }, { "label": "postalCode", "matchType": "EXACT" }, { "label": "streetType", "matchType": "EXACT" }, { "label": "postalCodeExt", "matchType": "EXACT" }, { "label": "streetDirectional", "matchType": "EXACT" }, { "label": "unitMatch", "matchType": "EXACT" } ] }, "source": { "label": "ggs" } }, "customFields": { "POBOX_ZONE": "N", "CSA_NUMBER": "104", "TYPE_SHORT": "VW", "THOROUGHFARE_TYPE": "VW", "ROAD_CLASS": "01", "MATCH_CODE": "V000", "COUNTY": "36083", "PB_KEY": "P0000GL41OME", "LANGUAGE": "en", "NON_DELIVERABLE": "N", "POINT_ID": "105104102", "CHECK_DIGIT": "8", "METRO_FLAG": "Y", "BLOCK": "360830523011008", "POST_THOROUGHFARE_TYPE": "VW", "QCITY": "361297000", "ZIP_FACILITY": "P", "LOT_CODE": "A", "LOT_NUM": "0052", "GEOHASH": "dredff441fxf", "CTYST_KEY": "V16572", "NAME": "GLOBAL", "ZIP_CARRTSORT": "D", "LORANGE": "1", "CLOSE_MATCH": "T", "ZIP_VALID": "Y", "STREET_SIDE": "L", "DATATYPE": "12", "INTERSECTION": "F", "ZIP_CITY_DELV": "Y", "LOC_CODE": "AP05", "GLOBAL_LOCATION_CODE": "662", "CART": "C099", "NAME_CITY": "TROY", "BLOCK_LEFT": "360830523011008", "COUNTY_FIPS": "36083", "PRECISION_LEVEL": "19", "HIRANGE": "1", "REC_TYPE": "S", "RESOLVED_LINE": "0", "PREF_CITY": "TROY", "CBSA_NUMBER": "10580", "ALT_FLAG": "B", "SEGMENT_DIRECTION": "F", "ADDRLINE_SHORT": "1 GLOBAL VW", "CONFIDENCE": "96", "HIZIP4": "8371", "DATATYPE_NAME": "MASTER LOCATION", "ORIG_DPBC": "01", "SEGMENT_PARITY": "L", "LOZIP4": "8371", "CSA_NAME": "ALBANY-SCHENECTADY, NY COMBINED STATISTICAL AREA", "DPBC": "01", "LASTLINE_SHORT": "TROY, NY 12180-8371", "CITY_SHORT": "TROY", "NAME_SHORT": "GLOBAL", "ZIP9": "121808371", "IS_ALIAS": "N01", "PRECISION_CODE": "S8H------A", "ZIP10": "12180-8371", "CBSA_NAME": "ALBANY-SCHENECTADY-TROY, NY METROPOLITAN STATISTICAL AREA", "RANGE_PARITY": "O" } } ] } ] } } } } } }, "400": { "description": "Invalid request for Lookup API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Not able to identify ABC country (DIS-LI-1016)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Lookup API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Lookup API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "413": { "description": "Request entity too large for Lookup API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "BATCH_SIZE_EXCEEDED", "errorMessage": "Batch size must not exceed 25 (DIS-LI-1014)" } ] } } } } } }, "429": { "description": "Too many requests for Lookup API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal server error for Lookup API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } }, "503": { "description": "Lookup Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "SERVICE_UNAVAILABLE", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-LI-1011)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/proximity-search": { "post": { "tags": [ "Address Proximity Search" ], "summary": "Address proximity search using location.", "description": "A reverse geo search functionality will enable the company to provide customers with personalized recommendations for nearby merchants that accept their card, enhancing the overall customer experience and driving card usage.\n\nINPUTS Required:\n\nDataset to Search (e.g., premium-address-points)\nLocation (expressed as Lat/Long, country) from where to start a Search\nDistance to Search and/or Max Results to return\n", "operationId": "proximity", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "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.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "requestBody": { "description": "Address proximity search sample request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressProximitySearchRequest" }, "examples": { "example": { "value": { "preferences": { "dataset": "premium-address-points", "maxResults": 1, "borderBufferKm": 25, "crossDatasetSearch": false, "autoRoute": true, "clientCoordSystemName": "EPSG:4326", "distance": { "value": 25, "distanceUnit": "KILOMETER" }, "customPreferences": {} }, "location": { "addressId": "1", "latitude": 37.718356, "longitude": -122.392016, "country": "USA" } } } } } }, "required": true }, "responses": { "200": { "description": "Address proximity search successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressProximitySearchResponse" }, "examples": { "example": { "value": { "response": { "addressId": "1", "status": "OK", "results": [ { "distance": 0.001655975923770516, "location": { "latitude": 37.718365, "longitude": -122.392001 }, "metadata": { "GEOID": "060750234002010", "ADDNUMBER": "1", "PBKEY": "P00002T1R18V", "COUNTRY": "USA", "FORMATTEDADDRESS": "1 REDONDO ST SAN FRANCISCO CA 94124-3538", "STREETSUFFIX": "ST", "POSTALCODE": "94124", "POSTALCODEEXT": "3538", "FIPS": "06075", "PROPTYPE": "R", "STREET": "REDONDO", "LANGCODE": "ENG", "ADMIN2": "SAN FRANCISCO", "ADMIN1": "CA", "CITY": "SAN FRANCISCO", "LOCCODE": "P05", "ADDRLINE4": "SAN FRANCISCO CA 94124-3538", "ADDRLINE1": "1 REDONDO ST", "STREETNAME": "REDONDO ST" } } ] } } } } } } }, "400": { "description": "Invalid request for Address proximity search API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Dataset is not provided in the request (DIS-LI-1031)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Address proximity search API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Address proximity search API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Address proximity search API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal server error for Address proximity search API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } }, "503": { "description": "Address proximity search service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "SERVICE_UNAVAILABLE", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-LI-1011)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/reverse-geocode": { "post": { "tags": [ "Reverse Geocode" ], "summary": "Reverse-geocode the addresses", "description": "This API takes latitude/longitude coordinates for a point as input and returns address information that is the best match for that point. It can take single input address or multiple input addresses and returns standardized US or international address and geocoding information. The Reverse-Geocode API supports global coverage.", "operationId": "reverseGeocode", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "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.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "requestBody": { "description": "Reverse-geocode sample request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReverseGeocodeRequest" }, "examples": { "example": { "value": { "preferences": { "maxResults": 1, "returnAllInfo": true, "factoryDescription": { "label": "", "featureSpecific": {} }, "clientLocale": "en_US", "clientCoordSysName": "", "distance": { "value": 150, "distanceUnit": "METER" }, "streetOffset": { "value": 7, "distanceUnit": "METER" }, "cornerOffset": { "value": 7, "distanceUnit": "METER" }, "fallbackToGeographic": true, "fallbackToPostal": true, "matchMode": "", "returnOfAdditionalFields": [], "originXY": [], "customPreferences": {} }, "locations": [ { "addressId": "1", "longitude": -73.704719, "latitude": 42.682251, "country": "USA" } ] } } } } }, "required": true }, "responses": { "200": { "description": "Location reverse-geocoded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReverseGeocodeResponse" }, "examples": { "example": { "value": { "responses": [ { "addressId": "1", "status": "OK", "results": [ { "score": 0, "address": { "formattedAddress": "1 GLOBAL VW, TROY NY 12180-8371, United States", "formattedStreetAddress": "1 GLOBAL VW", "formattedLocationAddress": "TROY, NY 12180-8371", "addressNumber": "1", "country": { "name": "United States", "isoAlpha2Code": "US", "isoAlpha3Code": "USA", "isoNumericCode": "840" }, "admin1": { "longName": "New York", "shortName": "NY" }, "admin2": { "longName": "RENSSELAER COUNTY", "shortName": "RENSSELAER COUNTY" }, "city": { "longName": "TROY", "shortName": "TROY" }, "postalCode": "12180", "postalCodeExt": "8371", "street": "GLOBAL" }, "addressLines": [ "1 GLOBAL VW", "TROY NY 12180-8371", "United States" ], "location": { "explanation": { "type": "ADDRESS_POINT", "description": "BUILDING", "designation": "CENTROID" }, "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -73.704443, 42.682242 ] } } }, "explanation": { "addressMatch": { "description": [ { "label": "placeName", "matchType": "NONE" }, { "label": "addressNumber", "matchType": "NONE" }, { "label": "admin1", "matchType": "EXACT" }, { "label": "admin2", "matchType": "NONE" }, { "label": "city", "matchType": "EXACT" }, { "label": "neighborhood", "matchType": "NONE" }, { "label": "suburb", "matchType": "NONE" }, { "label": "street", "matchType": "EXACT" }, { "label": "postalCode", "matchType": "NONE" }, { "label": "streetType", "matchType": "EXACT" }, { "label": "postalCodeExt", "matchType": "NONE" }, { "label": "streetDirectional", "matchType": "EXACT" }, { "label": "unitMatch", "matchType": "NONE" } ] }, "source": { "label": "ggs" } }, "customFields": { "POBOX_ZONE": "N", "CSA_NUMBER": "104", "TYPE_SHORT": "VW", "THOROUGHFARE_TYPE": "VW", "ROAD_CLASS": "01", "MATCH_CODE": "NP0", "COUNTY": "36083", "PB_KEY": "P0000GL41OME", "LANGUAGE": "en", "NON_DELIVERABLE": "N", "POINT_ID": "105104102", "CHECK_DIGIT": "8", "METRO_FLAG": "Y", "BLOCK": "360830523011008", "POST_THOROUGHFARE_TYPE": "VW", "QCITY": "361297000", "ZIP_FACILITY": "P", "LOT_CODE": "A", "LOT_NUM": "0052", "CTYST_KEY": "V16572", "NAME": "GLOBAL", "ZIP_CARRTSORT": "D", "LORANGE": "1", "CLOSE_MATCH": "T", "ZIP_VALID": "Y", "REVERSE_GEOCODE_DISTANCE": "22.555200000000003", "STREET_SIDE": "L", "DATATYPE": "12", "INTERSECTION": "F", "ZIP_CITY_DELV": "Y", "LOC_CODE": "AP05", "GLOBAL_LOCATION_CODE": "662", "CART": "C099", "NAME_CITY": "TROY", "BLOCK_LEFT": "360830523011008", "REVERSE_GEOCODE_DISTANCE_UNIT": "METERS", "COUNTY_FIPS": "36083", "PRECISION_LEVEL": "19", "HIRANGE": "1", "REC_TYPE": "S", "RESOLVED_LINE": "5", "PREF_CITY": "TROY", "CBSA_NUMBER": "10580", "ALT_FLAG": "B", "ADDRLINE_SHORT": "1 GLOBAL VW", "CONFIDENCE": "100", "DATATYPE_NAME": "MASTER LOCATION", "ORIG_DPBC": "01", "CSA_NAME": "ALBANY-SCHENECTADY, NY COMBINED STATISTICAL AREA", "DPBC": "01", "PERCENT_GEOCODE": "0.0", "LASTLINE_SHORT": "TROY, NY 12180-8371", "CITY_SHORT": "TROY", "NAME_SHORT": "GLOBAL", "ZIP9": "121808371", "IS_ALIAS": "N01", "PRECISION_CODE": "RS8A", "ZIP10": "12180-8371", "CBSA_NAME": "ALBANY-SCHENECTADY-TROY, NY METROPOLITAN STATISTICAL AREA" } } ] } ] } } } } } }, "206": { "description": "Location reverse-geocoded partially", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReverseGeocodeResponse" }, "examples": { "example": { "value": { "responses": [ { "addressId": "1", "errorMessage": "Not able to identify ABC country (DIS-LI-1016)", "status": "INVALID_REQUEST" }, { "addressId": "2", "status": "OK", "results": [ { "score": 0, "address": { "formattedAddress": "1 GLOBAL VW, TROY NY 12180-8371, United States", "formattedStreetAddress": "1 GLOBAL VW", "formattedLocationAddress": "TROY, NY 12180-8371", "addressNumber": "1", "country": { "name": "United States", "isoAlpha2Code": "US", "isoAlpha3Code": "USA", "isoNumericCode": "840" }, "admin1": { "longName": "New York", "shortName": "NY" }, "admin2": { "longName": "RENSSELAER COUNTY", "shortName": "RENSSELAER COUNTY" }, "city": { "longName": "TROY", "shortName": "TROY" }, "postalCode": "12180", "postalCodeExt": "8371", "street": "GLOBAL" }, "addressLines": [ "1 GLOBAL VW", "TROY NY 12180-8371", "United States" ], "location": { "explanation": { "type": "ADDRESS_POINT", "description": "BUILDING", "designation": "CENTROID" }, "feature": { "type": "Feature", "properties": { "crsName": "epsg:4326" }, "geometry": { "type": "Point", "coordinates": [ -73.704443, 42.682242 ] } } }, "explanation": { "addressMatch": { "description": [ { "label": "placeName", "matchType": "NONE" }, { "label": "addressNumber", "matchType": "NONE" }, { "label": "admin1", "matchType": "EXACT" }, { "label": "admin2", "matchType": "NONE" }, { "label": "city", "matchType": "EXACT" }, { "label": "neighborhood", "matchType": "NONE" }, { "label": "suburb", "matchType": "NONE" }, { "label": "street", "matchType": "EXACT" }, { "label": "postalCode", "matchType": "NONE" }, { "label": "streetType", "matchType": "EXACT" }, { "label": "postalCodeExt", "matchType": "NONE" }, { "label": "streetDirectional", "matchType": "EXACT" }, { "label": "unitMatch", "matchType": "NONE" } ] }, "source": { "label": "ggs" } }, "customFields": { "POBOX_ZONE": "N", "CSA_NUMBER": "104", "TYPE_SHORT": "VW", "THOROUGHFARE_TYPE": "VW", "ROAD_CLASS": "01", "MATCH_CODE": "NP0", "COUNTY": "36083", "PB_KEY": "P0000GL41OME", "LANGUAGE": "en", "NON_DELIVERABLE": "N", "POINT_ID": "105104102", "CHECK_DIGIT": "8", "METRO_FLAG": "Y", "BLOCK": "360830523011008", "POST_THOROUGHFARE_TYPE": "VW", "QCITY": "361297000", "ZIP_FACILITY": "P", "LOT_CODE": "A", "LOT_NUM": "0052", "CTYST_KEY": "V16572", "NAME": "GLOBAL", "ZIP_CARRTSORT": "D", "LORANGE": "1", "CLOSE_MATCH": "T", "ZIP_VALID": "Y", "REVERSE_GEOCODE_DISTANCE": "22.555200000000003", "STREET_SIDE": "L", "DATATYPE": "12", "INTERSECTION": "F", "ZIP_CITY_DELV": "Y", "LOC_CODE": "AP05", "GLOBAL_LOCATION_CODE": "662", "CART": "C099", "NAME_CITY": "TROY", "BLOCK_LEFT": "360830523011008", "REVERSE_GEOCODE_DISTANCE_UNIT": "METERS", "COUNTY_FIPS": "36083", "PRECISION_LEVEL": "19", "HIRANGE": "1", "REC_TYPE": "S", "RESOLVED_LINE": "5", "PREF_CITY": "TROY", "CBSA_NUMBER": "10580", "ALT_FLAG": "B", "ADDRLINE_SHORT": "1 GLOBAL VW", "CONFIDENCE": "100", "DATATYPE_NAME": "MASTER LOCATION", "ORIG_DPBC": "01", "CSA_NAME": "ALBANY-SCHENECTADY, NY COMBINED STATISTICAL AREA", "DPBC": "01", "PERCENT_GEOCODE": "0.0", "LASTLINE_SHORT": "TROY, NY 12180-8371", "CITY_SHORT": "TROY", "NAME_SHORT": "GLOBAL", "ZIP9": "121808371", "IS_ALIAS": "N01", "PRECISION_CODE": "RS8A", "ZIP10": "12180-8371", "CBSA_NAME": "ALBANY-SCHENECTADY-TROY, NY METROPOLITAN STATISTICAL AREA" } } ] } ] } } } } } }, "400": { "description": "Invalid request for Reverse Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Not able to identify ABC country (DIS-LI-1016)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Reverse Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Reverse Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "413": { "description": "Request entity too large for Reverse Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "BATCH_SIZE_EXCEEDED", "errorMessage": "Batch size must not exceed 25 (DIS-LI-1014)" } ] } } } } } }, "429": { "description": "Too many requests for Reverse Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal server error for Reverse Geocode API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } }, "503": { "description": "Reverse Geocode Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "SERVICE_UNAVAILABLE", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-LI-1011)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v1/verify": { "post": { "tags": [ "Address Verification" ], "summary": "Performs address verification", "description": "\nThis API performs address verification and standardization using the specified processing engine. Options are available to control matching and geocoding criteria, return values and other preferences. This API supports Global Coverage. This API Eliminate errors in address data and improves customer experience. The Address Verify API makes communication easier, faster and effortless by enriching customer details, keeping it up-to-date and maintaining its accuracy and consistency. It eliminates redundancy in reaching out to customers and makes it easy for distinct functional areas to work seamlessly in improving customer relationship.\n\nThe Verify API also supports Custom Preferences. These preferences are for use with any country dataset.\nFor more details on these preferences see Custom Preferences\n", "operationId": "verify", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "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.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "requestBody": { "description": "Verify sample request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" }, "examples": { "example": { "value": { "preferences": { "maxResults": 1, "returnAllInfo": true, "factoryDescription": { "label": "", "featureSpecific": {} }, "clientLocale": "en_US", "clientCoordSysName": "", "distance": { "value": 150, "distanceUnit": "METER" }, "streetOffset": { "value": 7, "distanceUnit": "METER" }, "cornerOffset": { "value": 7, "distanceUnit": "METER" }, "fallbackToGeographic": true, "fallbackToPostal": true, "matchMode": "", "returnOfAdditionalFields": [], "originXY": [], "customPreferences": {} }, "addresses": [ { "addressId": "1", "addressLines": [ "1700 District Ave #300 Burlington, MA" ], "country": "USA", "addressNumber": "", "admin1": "", "admin2": "", "city": "", "borough": "", "neighborhood": "", "suburb": "", "postalCode": "", "postalCodeExt": "", "placeName": "", "street": "", "building": "", "floor": "", "room": "", "unit": "", "unitType": "" } ] } } } } }, "required": true }, "responses": { "200": { "description": "Address(es) verified successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResponse" }, "examples": { "example": { "value": { "responses": [ { "addressId": "1", "status": "OK", "results": [ { "score": 97, "address": { "formattedAddress": "1700 DISTRICT AVE STE 300, BURLINGTON MA 01803-5231, United States", "formattedStreetAddress": "1700 DISTRICT AVE STE 300", "formattedLocationAddress": "BURLINGTON, MA 01803-5231", "unitType": "STE", "addressNumber": "1700", "country": { "name": "United States", "isoAlpha2Code": "US", "isoAlpha3Code": "USA", "isoNumericCode": "840" }, "admin1": { "longName": "Massachusetts", "shortName": "MA" }, "admin2": { "longName": "MIDDLESEX COUNTY", "shortName": "MIDDLESEX COUNTY" }, "city": { "longName": "BURLINGTON", "shortName": "BURLINGTON" }, "postalCode": "01803", "postalCodeExt": "5231", "street": "DISTRICT", "unit": "300" }, "addressLines": [ "1700 DISTRICT AVE STE 300", "BURLINGTON MA 01803-5231", "United States" ], "explanation": { "addressMatch": { "type": "ADDRESS", "description": [ { "label": "placeName", "matchType": "NONE" }, { "label": "addressNumber", "matchType": "EXACT" }, { "label": "admin1", "matchType": "EXACT" }, { "label": "admin2", "matchType": "NONE" }, { "label": "city", "matchType": "EXACT" }, { "label": "neighborhood", "matchType": "NONE" }, { "label": "suburb", "matchType": "NONE" }, { "label": "street", "matchType": "EXACT" }, { "label": "postalCode", "matchType": "NONE" }, { "label": "streetType", "matchType": "EXACT" }, { "label": "postalCodeExt", "matchType": "NONE" }, { "label": "streetDirectional", "matchType": "EXACT" }, { "label": "unitMatch", "matchType": "NONE" } ] }, "source": { "label": "ggs" } }, "customFields": { "RESBUS": "B", "POBOX_ZONE": "N", "LOTSIZE_METERS": "14677", "CSA_NUMBER": "148", "TYPE_SHORT": "AVE", "THOROUGHFARE_TYPE": "AVE", "HIUNIT": "300", "PARCEN_ELEVATION_METERS": "42.4", "ROAD_CLASS": "01", "MATCH_CODE": "S902", "COUNTY": "25017", "PB_KEY": "P0000BJ4F90Q", "LANGUAGE": "en", "UNIT_TYPE": "STE", "ADDRTYPE": "M", "INC_IND": "N", "BLOCK_2010": "250173324002012", "NON_DELIVERABLE": "N", "POINT_ID": "100893034", "CHECK_DIGIT": "5", "METRO_FLAG": "Y", "BLOCK": "250173324011003", "POST_THOROUGHFARE_TYPE": "AVE", "QCITY": "250065000", "ZIP_FACILITY": "P", "TFID": "258319428", "UNIT_RANGE_PARITY": "E", "APN_ID": "BURL M:000046 P:000051", "LOT_CODE": "A", "LOT_NUM": "0188", "CTYST_KEY": "V21569", "UACEPOP": "4382009", "NAME": "DISTRICT", "ZIP_CARRTSORT": "D", "PARENT_ID": "P0000BJ68DL3", "LORANGE": "1700", "CLOSE_MATCH": "T", "ZIP_VALID": "Y", "STREET_SIDE": "L", "DATATYPE": "12", "INTERSECTION": "F", "ZIP_CITY_DELV": "Y", "LOUNIT": "300", "LOC_CODE": "AP05", "CART": "C023", "NAME_CITY": "BURLINGTON", "BLOCK_LEFT": "250173324011003", "COUNTY_FIPS": "25017", "PRECISION_LEVEL": "19", "HIRANGE": "1700", "UACE": "09271", "REC_TYPE": "H", "HI_RISE_DFLT": "N", "URBANICITY": "L", "RESOLVED_LINE": "0", "MATCH_TYPE": "ADDRESS", "PARCEN_ELEVATION": "139", "PREF_CITY": "BURLINGTON", "CBSA_NUMBER": "14460", "ALT_FLAG": "B", "SEGMENT_DIRECTION": "F", "ADDRLINE_SHORT": "1700 DISTRICT AVE STE 300", "LOTSIZE": "157983", "CONFIDENCE": "89", "HIZIP4": "5231", "DATATYPE_NAME": "MASTER LOCATION", "ORIG_DPBC": "75", "SEGMENT_PARITY": "R", "CBSA_DIVISION_NAME": "CAMBRIDGE-NEWTON-FRAMINGHAM, MA METROPOLITAN DIVISION", "LOZIP4": "5231", "CSA_NAME": "BOSTON-WORCESTER-PROVIDENCE, MA-RI-NH COMBINED STATISTICAL AREA", "DPBC": "75", "LASTLINE_SHORT": "BURLINGTON, MA 01803-5231", "PLACE": "2509875", "CITY_SHORT": "BURLINGTON", "NAME_SHORT": "DISTRICT", "ZIP9": "018035231", "IS_ALIAS": "N01", "PRECISION_CODE": "S8HPNTSC-A", "ZIP10": "01803-5231", "CBSA_NAME": "BOSTON-CAMBRIDGE-NEWTON, MA-NH METROPOLITAN STATISTICAL AREA", "RANGE_PARITY": "E", "CBSA_DIVISION_NUMBER": "15764" } } ] } ] } } } } } }, "206": { "description": "Address(es) verified partially", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResponse" }, "examples": { "example": { "value": { "responses": [ { "addressId": "1", "errorMessage": "Not able to identify ABC country (DIS-LI-1016)", "status": "INVALID_REQUEST" }, { "addressId": "2", "status": "OK", "results": [ { "score": 97, "address": { "formattedAddress": "1700 DISTRICT AVE STE 300, BURLINGTON MA 01803-5231, United States", "formattedStreetAddress": "1700 DISTRICT AVE STE 300", "formattedLocationAddress": "BURLINGTON, MA 01803-5231", "unitType": "STE", "addressNumber": "1700", "country": { "name": "United States", "isoAlpha2Code": "US", "isoAlpha3Code": "USA", "isoNumericCode": "840" }, "admin1": { "longName": "Massachusetts", "shortName": "MA" }, "admin2": { "longName": "MIDDLESEX COUNTY", "shortName": "MIDDLESEX COUNTY" }, "city": { "longName": "BURLINGTON", "shortName": "BURLINGTON" }, "postalCode": "01803", "postalCodeExt": "5231", "street": "DISTRICT", "unit": "300" }, "addressLines": [ "1700 DISTRICT AVE STE 300", "BURLINGTON MA 01803-5231", "United States" ], "explanation": { "addressMatch": { "type": "ADDRESS", "description": [ { "label": "placeName", "matchType": "NONE" }, { "label": "addressNumber", "matchType": "EXACT" }, { "label": "admin1", "matchType": "EXACT" }, { "label": "admin2", "matchType": "NONE" }, { "label": "city", "matchType": "EXACT" }, { "label": "neighborhood", "matchType": "NONE" }, { "label": "suburb", "matchType": "NONE" }, { "label": "street", "matchType": "EXACT" }, { "label": "postalCode", "matchType": "NONE" }, { "label": "streetType", "matchType": "EXACT" }, { "label": "postalCodeExt", "matchType": "NONE" }, { "label": "streetDirectional", "matchType": "EXACT" }, { "label": "unitMatch", "matchType": "NONE" } ] }, "source": { "label": "ggs" } }, "customFields": { "RESBUS": "B", "POBOX_ZONE": "N", "LOTSIZE_METERS": "14677", "CSA_NUMBER": "148", "TYPE_SHORT": "AVE", "THOROUGHFARE_TYPE": "AVE", "HIUNIT": "300", "PARCEN_ELEVATION_METERS": "42.4", "ROAD_CLASS": "01", "MATCH_CODE": "S902", "COUNTY": "25017", "PB_KEY": "P0000BJ4F90Q", "LANGUAGE": "en", "UNIT_TYPE": "STE", "ADDRTYPE": "M", "INC_IND": "N", "BLOCK_2010": "250173324002012", "NON_DELIVERABLE": "N", "POINT_ID": "100893034", "CHECK_DIGIT": "5", "METRO_FLAG": "Y", "BLOCK": "250173324011003", "POST_THOROUGHFARE_TYPE": "AVE", "QCITY": "250065000", "ZIP_FACILITY": "P", "TFID": "258319428", "UNIT_RANGE_PARITY": "E", "APN_ID": "BURL M:000046 P:000051", "LOT_CODE": "A", "LOT_NUM": "0188", "CTYST_KEY": "V21569", "UACEPOP": "4382009", "NAME": "DISTRICT", "ZIP_CARRTSORT": "D", "PARENT_ID": "P0000BJ68DL3", "LORANGE": "1700", "CLOSE_MATCH": "T", "ZIP_VALID": "Y", "STREET_SIDE": "L", "DATATYPE": "12", "INTERSECTION": "F", "ZIP_CITY_DELV": "Y", "LOUNIT": "300", "LOC_CODE": "AP05", "CART": "C023", "NAME_CITY": "BURLINGTON", "BLOCK_LEFT": "250173324011003", "COUNTY_FIPS": "25017", "PRECISION_LEVEL": "19", "HIRANGE": "1700", "UACE": "09271", "REC_TYPE": "H", "HI_RISE_DFLT": "N", "URBANICITY": "L", "RESOLVED_LINE": "0", "MATCH_TYPE": "ADDRESS", "PARCEN_ELEVATION": "139", "PREF_CITY": "BURLINGTON", "CBSA_NUMBER": "14460", "ALT_FLAG": "B", "SEGMENT_DIRECTION": "F", "ADDRLINE_SHORT": "1700 DISTRICT AVE STE 300", "LOTSIZE": "157983", "CONFIDENCE": "89", "HIZIP4": "5231", "DATATYPE_NAME": "MASTER LOCATION", "ORIG_DPBC": "75", "SEGMENT_PARITY": "R", "CBSA_DIVISION_NAME": "CAMBRIDGE-NEWTON-FRAMINGHAM, MA METROPOLITAN DIVISION", "LOZIP4": "5231", "CSA_NAME": "BOSTON-WORCESTER-PROVIDENCE, MA-RI-NH COMBINED STATISTICAL AREA", "DPBC": "75", "LASTLINE_SHORT": "BURLINGTON, MA 01803-5231", "PLACE": "2509875", "CITY_SHORT": "BURLINGTON", "NAME_SHORT": "DISTRICT", "ZIP9": "018035231", "IS_ALIAS": "N01", "PRECISION_CODE": "S8HPNTSC-A", "ZIP10": "01803-5231", "CBSA_NAME": "BOSTON-CAMBRIDGE-NEWTON, MA-NH METROPOLITAN STATISTICAL AREA", "RANGE_PARITY": "E", "CBSA_DIVISION_NUMBER": "15764" } } ] } ] } } } } } }, "400": { "description": "Invalid request for Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Not able to identify ABC country (DIS-LI-1016)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "413": { "description": "Request entity too large for Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "BATCH_SIZE_EXCEEDED", "errorMessage": "Batch size must not exceed 25 (DIS-LI-1014)" } ] } } } } } }, "429": { "description": "Too many requests for Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal server error for Verify API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } }, "503": { "description": "Verify Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "SERVICE_UNAVAILABLE", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-LI-1011)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } }, "/v2/express-autocomplete": { "post": { "tags": [ "Address Autocomplete Express" ], "summary": "Enhances address autocompletion", "description": "\nThis 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.\n\n**SEARCH_TYPE** (via `customPreferences`):\n\nThe API supports two values for `SEARCH_TYPE`:\n- **`ADDRESS`** — Returns address-based autocomplete candidates. This is the **default** when `SEARCH_TYPE` is not specified or omitted.\n- **`POI`** — Returns Point of Interest autocomplete candidates.\n\nList of supported countries for Address Autocomplete Express API with applicable **SEARCH_TYPE**:\n\n| SEARCH_TYPE | COUNTRY |\n|-------------|-------------|\n| 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) |\n| POI | USA, CAN, GBR, CHN, JPN, HKG, THA, TWN, EGY, RUS, COL, AUS |\n\nNote: This API is only available in US region.\n\n**Native Script Support** (via `preferences.clientLocale`):\n\nUse `clientLocale` to specify the language for native-script autocomplete results (optional, ISO 639-1 code).\nSupported values: `zh` (Chinese), `ja` (Japanese standard), `ka` (Japanese Katakana), `ru` (Russian), `th` (Thai), `ar` (Arabic).\n\n**filterBias** (via `preferences.filterBias`):\n\nThe 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.\n\n- **`filter`** — supports both `fields.include` and `fields.exclude`. Supported include keys: `city`, `postalCode`, `poiCategory`.\n- **`bias`** — supports `fields.include` only (`fields.exclude` is not allowed and will return an INVALID_REQUEST error). Supported include keys: `city`, `postalCode`.\n\n> **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.\n\n**distance** (via `preferences.distance`):\n\nDefines the search radius around the input address. Example: `{\"value\": 150.0, \"distanceUnit\": \"METER\"}`.\n\n", "operationId": "autocompleteExpressV2", "parameters": [ { "name": "X-Request-Id", "in": "header", "description": "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.", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "X-Transaction-Id", "in": "header", "description": "To handle a large number of calls and keep things organized, we group API calls for the same address into a single \"transaction.\"\n\nA transaction is considered complete when:\n\n- 15 seconds have passed, or\n- 12 API calls have been made, whichever happens first.\n\n**Transaction ID Behavior:**\n- The Transaction ID (GUID) must be sent as part of the `x-transaction-id` header in each API request.\n- We recommend users generate a new Transaction ID for every new transaction.\n- 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.\n\n**Examples:**\n\n**1. 15-Second Scenario:**\nA user starts typing an address and includes a Transaction ID (e.g., `1234-5678-ABCD`) in the `x-transaction-id` header:\n- They make 4 calls (e.g., for `\"12\"`, `\"123\"`, `\"123 Main\"`, `\"123 Main St\"`) within 15 seconds.\n- After 15 seconds, the transaction is marked complete.\n- 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`),\n our system will treat these additional calls as part of a new transaction.\n\n**2. 12-Call Scenario:**\nAnother user types quickly and includes a Transaction ID (e.g., `5678-1234-EFGH`) in the `x-transaction-id` header:\n- They make 12 calls (e.g., for `\"1\"`, `\"12\"`, `\"123\"`, ..., `\"123 Main St Apt 4\"`) within 3 seconds.\n- Since the 12-call limit is reached, the transaction is marked complete.\n- If the user continues to refine or add to their input using the same Transaction ID (`5678-1234-EFGH`),\n our system will treat these additional calls as part of a new transaction.\n", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "requestBody": { "description": "Autocomplete express v2 sample request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutocompleteV2Request" }, "examples": { "example": { "value": { "preferences": { "maxResults": 5, "returnAllInfo": true, "factoryDescription": { "label": "", "featureSpecific": {} }, "clientLocale": "en_US", "clientCoordSysName": "", "distance": { "value": 150, "distanceUnit": "METER" }, "streetOffset": { "value": 7, "distanceUnit": "METER" }, "cornerOffset": { "value": 7, "distanceUnit": "METER" }, "fallbackToGeographic": true, "fallbackToPostal": true, "matchMode": "", "returnOfAdditionalFields": [], "originXY": [], "customPreferences": { "SEARCH_TYPE": "ADDRESS" }, "filterBias": { "type": "filter", "fields": { "include": { "postalCode": { "value": "1218" } }, "exclude": { "city": { "value": "Troy" } } } } }, "address": { "addressLines": [ "350 Jordan" ], "country": "USA", "addressNumber": "", "admin1": "", "admin2": "", "city": "", "borough": "", "neighborhood": "", "suburb": "", "postalCode": "", "postalCodeExt": "", "placeName": "", "street": "", "building": "", "floor": "", "room": "", "unit": "", "unitType": "" } } } } } }, "required": true }, "responses": { "200": { "description": "Address predicted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutocompleteResponse" }, "examples": { "example": { "value": { "response": { "status": "OK", "predictions": [ { "prediction": "350 JORDAN RD, TROY 12180-8352", "address": { "formattedAddress": "350 JORDAN RD, TROY 12180-8352", "formattedStreetAddress": "350 Jordan Rd", "formattedLocationAddress": "Troy NY 12180-8352", "addressNumber": "350", "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "NY", "shortName": "NY" }, "city": { "longName": "Troy", "shortName": "Troy" }, "postalCode": "12180", "postalCodeExt": "8352", "street": "Jordan Rd" }, "addressLines": [ "350 JORDAN RD", "TROY 12180-8352" ], "customFields": { "PB_KEY": "P0000GL638OL", "FORMATTED_STRING": "350 JORDAN RD, TROY 12180-8352", "POSTAL_VERIFIED": "NO" } }, { "prediction": "350 JORDAN RD STE 2, TROY 12180-8358", "address": { "formattedAddress": "350 JORDAN RD STE 2, TROY 12180-8358", "formattedStreetAddress": "350 Jordan Rd", "formattedLocationAddress": "Troy NY 12180-8358", "addressNumber": "350", "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "NY", "shortName": "NY" }, "city": { "longName": "Troy", "shortName": "Troy" }, "postalCode": "12180", "postalCodeExt": "8358", "street": "Jordan Rd", "unit": "Ste 2" }, "addressLines": [ "350 JORDAN RD STE 2", "TROY 12180-8358" ], "customFields": { "PB_KEY": "P0000GL41OMJ", "FORMATTED_STRING": "350 JORDAN RD STE 2, TROY 12180-8358", "UNIT_INFO": "Ste 2", "POSTAL_VERIFIED": "YES" } }, { "prediction": "350 JORDAN RD STE 3, TROY 12180-8358", "address": { "formattedAddress": "350 JORDAN RD STE 3, TROY 12180-8358", "formattedStreetAddress": "350 Jordan Rd", "formattedLocationAddress": "Troy NY 12180-8358", "addressNumber": "350", "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "NY", "shortName": "NY" }, "city": { "longName": "Troy", "shortName": "Troy" }, "postalCode": "12180", "postalCodeExt": "8358", "street": "Jordan Rd", "unit": "Ste 3" }, "addressLines": [ "350 JORDAN RD STE 3", "TROY 12180-8358" ], "customFields": { "PB_KEY": "P0000GL41OMK", "FORMATTED_STRING": "350 JORDAN RD STE 3, TROY 12180-8358", "UNIT_INFO": "Ste 3", "POSTAL_VERIFIED": "YES" } }, { "prediction": "350 JORDAN RD STE 1, TROY 12180-8358", "address": { "formattedAddress": "350 JORDAN RD STE 1, TROY 12180-8358", "formattedStreetAddress": "350 Jordan Rd", "formattedLocationAddress": "Troy NY 12180-8358", "addressNumber": "350", "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "NY", "shortName": "NY" }, "city": { "longName": "Troy", "shortName": "Troy" }, "postalCode": "12180", "postalCodeExt": "8358", "street": "Jordan Rd", "unit": "Ste 1" }, "addressLines": [ "350 JORDAN RD STE 1", "TROY 12180-8358" ], "customFields": { "PB_KEY": "P0000GL41OMI", "FORMATTED_STRING": "350 JORDAN RD STE 1, TROY 12180-8358", "UNIT_INFO": "Ste 1", "POSTAL_VERIFIED": "YES" } }, { "prediction": "350 JORDAN DR, CLAYTON 19938-2414", "address": { "formattedAddress": "350 JORDAN DR, CLAYTON 19938-2414", "formattedStreetAddress": "350 Jordan Dr", "formattedLocationAddress": "Clayton DE 19938-2414", "addressNumber": "350", "country": { "isoAlpha3Code": "USA" }, "admin1": { "longName": "DE", "shortName": "DE" }, "city": { "longName": "Clayton", "shortName": "Clayton" }, "postalCode": "19938", "postalCodeExt": "2414", "street": "Jordan Dr" }, "addressLines": [ "350 JORDAN DR", "CLAYTON 19938-2414" ], "customFields": { "PB_KEY": "P00004N1G1NF", "FORMATTED_STRING": "350 JORDAN DR, CLAYTON 19938-2414", "POSTAL_VERIFIED": "YES" } } ] } } } } } } }, "400": { "description": "Invalid request for Autocomplete Express API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_REQUEST", "errorMessage": "Not able to identify ABC country (DIS-LI-1016)" } ] } } } } } }, "401": { "description": "Unauthorized: Invalid token for Autocomplete Express API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INVALID_TOKEN", "errorMessage": "Unauthorized (DIS-1001)" } ] } } } } } }, "403": { "description": "Forbidden for Autocomplete Express API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "FORBIDDEN", "errorMessage": "You do not have permission to access this API (DIS-1002)" } ] } } } } } }, "429": { "description": "Too many requests for Autocomplete Express API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "TOO_MANY_REQUESTS", "errorMessage": "Rate limit exceeded (DIS-1005)" } ] } } } } } }, "500": { "description": "Internal server error for Autocomplete Express API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "INTERNAL_ERROR", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)" } ] } } } } } }, "503": { "description": "Autocomplete Express Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "example": { "value": { "errors": [ { "status": "SERVICE_UNAVAILABLE", "errorMessage": "Issue with internal services. Please try again after sometime (DIS-LI-1011)" } ] } } } } } } }, "security": [ { "bearerAuth": [] }, { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "AddressMatch": { "type": "object", "properties": { "description": { "type": "array", "description": "list of match descriptions", "items": { "$ref": "#/components/schemas/MatchDescription" } }, "type": { "$ref": "#/components/schemas/MatchType" } }, "description": "Describes the quality of address matching based on the user input address" }, "AddressProximitySearchDistance": { "type": "object", "properties": { "value": { "type": "number", "description": "Distance of the radius in which to search for a match. Default is 25.", "format": "double", "example": 25 }, "distanceUnit": { "$ref": "#/components/schemas/DistanceUnit" } }, "description": "Specifies the search radius distance and unit for a proximity search." }, "AddressProximitySearchLocationDetail": { "required": [ "country", "latitude", "longitude" ], "type": "object", "properties": { "addressId": { "type": "string", "description": "Address Id for the request", "example": "1" }, "longitude": { "type": "number", "description": "longitude (x)", "format": "double", "example": -73.704719 }, "latitude": { "type": "number", "description": "latitude (y)", "format": "double", "example": 42.682251 }, "country": { "type": "string", "description": "Name of country in ISO 3166-1 Alpha-2 or Alpha-3 format, or a common name of the country", "example": "USA" } }, "description": "List of object contains country and coordinates" }, "AddressProximitySearchPreferences": { "required": [ "dataset" ], "type": "object", "properties": { "dataset": { "minLength": 1, "type": "string", "description": "The dataset to search against (e.g. premium-address-points).", "example": "premium-address-points" }, "maxResults": { "type": "integer", "description": "Maximum number of results to return. Default: 50", "format": "int32", "example": 10 }, "customPreferences": { "type": "object", "additionalProperties": { "type": "string" }, "description": "For use against any country dataset, define custom preferences to control additional functionality.", "example": { "CLOSEST": "true" } }, "distance": { "description": "Specifies the search radius distance and unit. Default is 25 kilometers.", "allOf": [ { "$ref": "#/components/schemas/AddressProximitySearchDistance" } ] }, "borderBufferKm": { "type": "number", "description": "Buffer in kilometres around dataset borders to include candidates from neighbouring datasets. Default: 50.0 km", "format": "double", "example": 25 }, "crossDatasetSearch": { "type": "boolean", "description": "Whether to search across multiple datasets when the query point is near a border. Default: false", "example": false }, "autoRoute": { "type": "boolean", "description": "Whether to automatically route the request to the most appropriate dataset based on coordinates. Default: true", "example": true }, "clientCoordSystemName": { "type": "string", "description": "Client coordinate system name", "example": "EPSG:4326" } }, "description": "Preferences for address proximity search" }, "AddressProximitySearchRequest": { "required": [ "location", "preferences" ], "type": "object", "properties": { "preferences": { "description": "Preferences for the address proximity search request", "allOf": [ { "$ref": "#/components/schemas/AddressProximitySearchPreferences" } ] }, "location": { "description": "Location details containing latitude, longitude and country for the address proximity search", "allOf": [ { "$ref": "#/components/schemas/AddressProximitySearchLocationDetail" } ] } }, "description": "Request for address proximity search" }, "AddressProximitySearchResponse": { "type": "object", "properties": { "response": { "description": "Address Proximity search response containing status, results and error details", "allOf": [ { "$ref": "#/components/schemas/AddressProximitySearchResponseBody" } ] } }, "description": "Response for address proximity search" }, "AddressProximitySearchResponseBody": { "type": "object", "properties": { "addressId": { "type": "string", "description": "Address Id of the response", "example": "1" }, "errorMessage": { "type": "string", "description": "Error message from the underlying service", "example": "Not able to identify dataset" }, "status": { "$ref": "#/components/schemas/Status" }, "results": { "type": "array", "description": "List of address proximity search results", "items": { "$ref": "#/components/schemas/AddressProximitySearchResult" } } }, "description": "Address proximity search response body" }, "AddressProximitySearchResponseLocation": { "type": "object", "properties": { "latitude": { "type": "number", "description": "Latitude of the location", "format": "double", "example": 40.7887 }, "longitude": { "type": "number", "description": "Longitude of the location", "format": "double", "example": -73.0393 } }, "description": "Location details for address proximity search response" }, "AddressProximitySearchResult": { "type": "object", "properties": { "distance": { "type": "number", "description": "Distance from the query point to this result in kilometres", "format": "double", "example": 0.42 }, "location": { "description": "Geographic coordinates of the result", "allOf": [ { "$ref": "#/components/schemas/AddressProximitySearchResponseLocation" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Key-value map of dataset fields associated with this result", "example": { "COUNTRY": "USA", "POSTALCODE": "00501" } } }, "description": "A single result from a proximity search" }, "AdminField": { "type": "object", "properties": { "longName": { "type": "string", "description": "Long name", "example": "New York or Maharashtra" }, "shortName": { "type": "string", "description": "Short name", "example": "NY" } }, "description": "Specifies the geographic area like: admin1, admin2, city, neighborhood, suburb, borough." }, "AutocompletePostalCityAddress": { "required": [ "country" ], "type": "object", "properties": { "type": { "type": "string", "description": "Defines the output as either POSTAL or CITY, tailored for postal or city-oriented results", "example": "POSTAL" }, "postAddress": { "type": "string", "description": "Specifies a city or postal code", "example": "12180" }, "country": { "type": "string", "description": "Name of country in ISO 3166-1 Alpha-2 or Alpha-3 format, or a common name of the country", "example": "USA" } }, "description": "Displays the components of the address" }, "AutocompletePostalCityPredictionResponse": { "required": [ "status" ], "type": "object", "properties": { "status": { "$ref": "#/components/schemas/Status" }, "errorMessage": { "type": "string", "description": "Error message from the underlying service", "example": "Not able to identify ABC country" }, "predictions": { "type": "array", "description": "List of AutoComplete Responses", "items": { "$ref": "#/components/schemas/AutocompletePostalCityPredictionResult" } } }, "description": "Prediction response for postal-city request" }, "AutocompletePostalCityPredictionResult": { "type": "object", "properties": { "address": { "description": "postal-city response address", "allOf": [ { "$ref": "#/components/schemas/AutocompletePostalCityResponseAddress" } ] }, "location": { "description": "postal-city response location coordinate", "allOf": [ { "$ref": "#/components/schemas/Location" } ] } }, "description": "Autocomplete postal and city results" }, "AutocompletePostalCityRequest": { "required": [ "address" ], "type": "object", "properties": { "address": { "description": "autocomplete postal-city address request", "allOf": [ { "$ref": "#/components/schemas/AutocompletePostalCityAddress" } ] } }, "description": "Request for autocomplete postal-city", "allOf": [ { "$ref": "#/components/schemas/BaseRequest" } ] }, "AutocompletePostalCityResponse": { "type": "object", "properties": { "response": { "description": "Autocomplete postal-city response", "allOf": [ { "$ref": "#/components/schemas/AutocompletePostalCityPredictionResponse" } ] } }, "description": "Response for autocomplete postal-city" }, "AutocompletePostalCityResponseAddress": { "type": "object", "properties": { "country": { "description": "county information", "allOf": [ { "$ref": "#/components/schemas/CountryField" } ] }, "admin1": { "description": "Specifies the admin1 information of address.", "allOf": [ { "$ref": "#/components/schemas/AdminField" } ] }, "admin2": { "description": "Specifies the admin2 information of address.", "allOf": [ { "$ref": "#/components/schemas/AdminField" } ] }, "city": { "description": "Specifies the city information", "allOf": [ { "$ref": "#/components/schemas/AdminField" } ] }, "postalCode": { "type": "string", "description": "Postal code", "example": "12180" } }, "description": "Displays the components of the postal-city response address" }, "AutocompleteRequest": { "required": [ "address" ], "type": "object", "properties": { "address": { "description": "address for autocomplete", "allOf": [ { "$ref": "#/components/schemas/RequestAddress" } ] } }, "description": "Request for autocomplete", "allOf": [ { "$ref": "#/components/schemas/BaseRequest" } ] }, "AutocompleteResponse": { "type": "object", "properties": { "response": { "description": "Prediction response", "allOf": [ { "$ref": "#/components/schemas/PredictionResponse" } ] } }, "description": "Response for autocomplete" }, "AutocompleteV2Preferences": { "type": "object", "properties": { "fallbackToPostal": { "type": "boolean", "description": "Specifies whether to attempt to determine a post code centroid when an address-level geocode cannot be determined. Optional.", "example": false }, "returnAllInfo": { "type": "boolean", "description": "Specifies whether to return all available information for each candidate.", "example": true }, "fallbackToGeographic": { "type": "boolean", "description": "Specifies whether to attempt to determine a geographic centroid when an address-level geocode cannot be determined. Optional.", "example": false }, "distance": { "description": "distance the defined search radius (default is 5 meters)..", "allOf": [ { "$ref": "#/components/schemas/Distance" } ] }, "streetOffset": { "description": "streetOffset specifies the offset distance from the street segments to use in street-level geocoding (Default 5 meters).", "allOf": [ { "$ref": "#/components/schemas/Distance" } ] }, "cornerOffset": { "description": "Specifies the distance to offset the street end points in street-level matching (default is 7 meters).", "allOf": [ { "$ref": "#/components/schemas/Distance" } ] }, "maxResults": { "type": "integer", "description": "The maximum number of candidates to return. Default = 1.", "format": "int32", "example": 1 }, "factoryDescription": { "description": "description of address processor to process the request.", "allOf": [ { "$ref": "#/components/schemas/FactoryDescription" } ] }, "customPreferences": { "type": "object", "additionalProperties": { "type": "string" }, "description": "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.", "example": { "DATA_OPTION": "PREMIUM" } }, "clientLocale": { "title": "Locale", "type": "string", "description": "Specifies the locale value. For example, specify \"th\" for the Thai language.", "example": "zh", "allOf": [ { "$ref": "#/components/schemas/Locale" } ] }, "clientCoordSysName": { "type": "string", "description": "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.", "example": "EPSG:4326" }, "matchMode": { "type": "string", "description": "Match modes determine the leniency used to make a match between the input address and the reference data.", "example": "EXACT" }, "originXY": { "type": "array", "description": "XY coordinates of the origin address.", "example": [ 0, 0 ], "items": { "type": "number", "format": "double" } }, "returnOfAdditionalFields": { "type": "array", "description": "This lets the user control which additional fields they want to have returned if they do not want to return all info.", "example": [ "RESULT_CODE", "PRECISION_CODE" ], "items": { "type": "string" } }, "filterBias": { "title": "filterBias", "description": "Specifies the filterBias value either bias or filter", "allOf": [ { "$ref": "#/components/schemas/FilterBias" } ] } }, "description": "This class uses ExpressPreferences to add FilterBias for Autocomplete Express Functionality" }, "AutocompleteV2Request": { "required": [ "address" ], "type": "object", "properties": { "preferences": { "description": "preference for the request", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AutocompleteV2Preferences" } ] }, "address": { "description": "address for autocomplete", "allOf": [ { "$ref": "#/components/schemas/RequestAddress" } ] } }, "description": "Request for autocomplete express V2" }, "BaseRequest": { "type": "object", "properties": { "preferences": { "description": "preference for the request", "allOf": [ { "$ref": "#/components/schemas/Preferences" } ] } }, "description": "Basic request structure for geo-addressing APIs" }, "CountryField": { "type": "object", "properties": { "name": { "type": "string", "description": "Common name of the country", "example": "UNITED STATES" }, "isoAlpha2Code": { "type": "string", "description": "Alphabetic code (alpha-2)", "example": "US" }, "isoAlpha3Code": { "type": "string", "description": "Alphabetic code (alpha-3)", "example": "USA" }, "isoNumericCode": { "type": "string", "description": "Numeric code (numeric-3)", "example": "840" } }, "description": "Values are based on the ISO 3166-1 standard for country codes (returned in alpha-2, alpha-3, or numeric format)" }, "DecodeStatus": { "type": "string", "description": "Decode operation status", "example": "OK", "enum": [ "OK", "ERROR", "INVALID_REQUEST" ] }, "Distance": { "type": "object", "properties": { "value": { "type": "number", "description": "Distance of the radius in which to search for a match. Default is 5.", "format": "double", "example": 5 }, "distanceUnit": { "$ref": "#/components/schemas/DistanceUnit" } }, "description": "'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)." }, "DistanceUnit": { "type": "string", "description": "Distance unit", "example": "METER", "enum": [ "FOOT", "METER", "MILE", "KILOMETER" ] }, "ErrorDetail": { "required": [ "status" ], "type": "object", "properties": { "status": { "type": "string", "description": "Status of the response", "example": "INVALID_REQUEST" }, "errorMessage": { "type": "string", "description": "Error message from the underlying service", "example": "Not able to identify ABC country" }, "addressId": { "type": "string", "description": "Address Id of the response", "example": "1" } }, "description": "Details of Error" }, "ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "description": "list of errors", "items": { "$ref": "#/components/schemas/ErrorDetail" } } }, "description": "Response object in case of error" }, "ExplainAddressCodeItemRequest": { "required": [ "code" ], "type": "object", "properties": { "id": { "type": "string", "description": "Optional identifier for mapping responses to requests", "nullable": true, "example": "1" }, "code": { "minLength": 1, "type": "string", "description": "The address code to explain", "example": "V4-D4M0B0U0F0G0P4S4Q0X0A0T4E0R4W0Z4Y6C4-5" } }, "description": "Single address code item to explain" }, "ExplainAddressCodeRequest": { "required": [ "codeType", "codes" ], "type": "object", "properties": { "codeType": { "minLength": 1, "type": "string", "description": "Type of address code (e.g., GlobalMatchCode)", "example": "GlobalMatchCode" }, "codes": { "minItems": 1, "type": "array", "description": "List of address codes to explain", "items": { "$ref": "#/components/schemas/ExplainAddressCodeItemRequest" } }, "responseOptions": { "description": "Options for controlling response details (e.g., includeOfficialDescription)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ResponseOptions" } ] } }, "description": "Request to explain one or more address codes" }, "ExplainAddressCodeResponse": { "type": "object", "properties": { "responses": { "type": "array", "description": "List of responses corresponding to each code in the request", "items": { "$ref": "#/components/schemas/ExplainAddressCodeResponseItem" } }, "documentationLink": { "type": "string", "description": "URL to API documentation for interpreting the response and understanding code types", "example": "https://help.cloud.precisely.com/r/t/1737727574924/2025-11-18/Precisely-Data-Integrity-Suite/disapi/Latest/en-US/Data-Integrity-Suite-APIs/Global-Match-Code" }, "generatedAt": { "type": "string", "description": "Response creation timestamp in ISO-8601 format", "example": "2025-12-18T13:48:29.842427575Z" } }, "description": "Response containing explained address codes with insights and metadata" }, "ExplainAddressCodeResponseItem": { "required": [ "status" ], "type": "object", "properties": { "id": { "type": "string", "description": "Optional client-provided identifier for correlation", "nullable": true, "example": "1" }, "status": { "$ref": "#/components/schemas/DecodeStatus" }, "result": { "description": "Decoded result object when status is OK", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ExplainResult" } ] }, "errorMessage": { "type": "string", "description": "Error message if decoding failed", "nullable": true, "example": "Invalid code format for GlobalMatchCode in the request (DIS-LI-1040): verification level must be 1-4" } }, "description": "Response for each explain code request item" }, "ExplainResult": { "type": "object", "properties": { "codeType": { "type": "string", "description": "Type of address code", "example": "GlobalMatchCode" }, "customerInsightSummary": { "type": "string", "description": "Customer insight summary", "example": "Address premise verified with high confidence." }, "officialDescription": { "type": "object", "description": "Official technical description (when requested)", "nullable": true, "example": { "addressMatchStatus": { "symbol": "V4", "status": "Verified", "verificationLevel": 4, "verificationLevelLabel": "Premise verified" }, "componentMatchStatus": { "P": { "label": "Premise/House Number", "value": 4, "meaning": "Verified without changes" }, "S": { "label": "Street", "value": 4, "meaning": "Verified without changes" }, "Z": { "label": "Postcode/Zip Code", "value": 4, "meaning": "Verified without changes" }, "C": { "label": "Country", "value": 4, "meaning": "Verified without changes" } }, "matchConfidence": { "value": 5, "label": "High Confidence" } } } }, "description": "Decoded address code result" }, "Explanation": { "type": "object", "properties": { "identifier": { "type": "string", "description": "An ID generated from the underlying source reference data of an address.", "example": "Geocoder" }, "addressMatch": { "description": "Describes the quality of address matching based on the user input address", "allOf": [ { "$ref": "#/components/schemas/AddressMatch" } ] }, "source": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Returns information about the address processor.", "example": { "label": "ggs" } } }, "description": "Describes the level of matching for each component of an address" }, "FactoryDescription": { "type": "object", "properties": { "label": { "type": "string", "description": "Sets the addressing processor based on the configured data. Labels are case-sensitive and must be lowercase. Default is \"\".", "example": "asd" }, "featureSpecific": { "description": "Ability to map a feature to an address processor, based on specified label.", "example": { "LOOKUP": "ggs" }, "allOf": [ { "properties": { "GEOCODE": { "type": "string" }, "PARSE": { "type": "string" }, "VERIFY": { "type": "string" }, "REVERSE_GEOCODE": { "type": "string" }, "INTERACTIVE": { "type": "string" }, "LOOKUP": { "type": "string" } } } ] } }, "description": "Controls which address processor will process the request." }, "FilterBias": { "required": [ "fields" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/FilterBiasType" }, "fields": { "description": "Specifies which fields to be included or excluded in the biasing or filtering", "allOf": [ { "$ref": "#/components/schemas/FilterBiasFields" } ] } }, "description": "'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" }, "FilterBiasField": { "type": "object", "properties": { "value": { "type": "string", "description": "Specifies the value of corresponding field used for biasing", "example": "12180" } }, "description": "Specifies what field to be added for biasing" }, "FilterBiasFields": { "type": "object", "properties": { "include": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/FilterBiasField" }, "description": "Specifies which fields to be included biasing", "example": { "include": { "postalCode": { "value": "12180" } } } }, "exclude": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/FilterBiasField" }, "description": "Specifies which fields to be excluded in filters", "nullable": true, "example": { "exclude": { "postalCode": { "value": "12180" } } } } }, "description": "'fields' specifies which fields to be included or excluded in the biasing" }, "FilterBiasType": { "type": "string", "description": "Contains the value of the filterBias type, either bias or filter", "example": "bias", "enum": [ "bias", "filter" ], "x-enum-varnames": [ "bias", "filter" ] }, "GeocodeRequest": { "required": [ "addresses" ], "type": "object", "properties": { "addresses": { "minItems": 1, "type": "array", "description": "list of addresses for geocode", "items": { "$ref": "#/components/schemas/RequestAddressWithId" } } }, "description": "Request for geocode", "allOf": [ { "$ref": "#/components/schemas/BaseRequest" } ] }, "GeocodeResponse": { "type": "object", "properties": { "responses": { "type": "array", "description": "list of geocode responses", "items": { "$ref": "#/components/schemas/Response" } } }, "description": "Response for geocode" }, "Geometry": { "type": "object", "properties": { "type": { "type": "string", "description": "Geometry type. The return value is always Point", "example": "Point" }, "coordinates": { "type": "array", "description": "Coordinates as x (longitude) and y (latitude) separated by a comma", "example": [ -73.704719, 42.682251 ], "items": { "type": "number", "format": "double" } }, "foreignMembers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Foreign Members", "example": { "city": "New York", "population": "8419600", "founded": "1624" } } }, "description": "Provides the candidate's geometry" }, "ISO20022Address": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of postal address structure according to ISO 20022 standard", "example": "PostalAddress27" }, "format": { "type": "string", "description": "Format of the address representation", "example": "STRUCTURED" }, "elements": { "description": "Detailed address elements following ISO 20022 field definitions", "allOf": [ { "$ref": "#/components/schemas/ISO20022AddressElements" } ] } }, "description": "ISO 20022 PostalAddress27 structure containing address type, format, and elements" }, "ISO20022AddressElements": { "type": "object", "properties": { "StrtNm": { "type": "string", "description": "Street name (StrtNm) - Name of the street or thoroughfare", "example": "Main Street" }, "BldgNb": { "type": "string", "description": "Building number (BldgNb) - Number that identifies the position of a building on a street", "example": "123" }, "BldgNm": { "type": "string", "description": "Building name (BldgNm) - Name of the building or house", "example": "Tech Plaza" }, "UnitNb": { "type": "string", "description": "Unit number (UnitNb) - Number that identifies a unit within a building", "example": "5A" }, "Room": { "type": "string", "description": "Room (Room) - Information that identifies a room within a building", "example": "301" }, "PstBx": { "type": "string", "description": "Post box (PstBx) - Numbered box in a post office assigned to a person or organization", "example": "PO Box 456" }, "PstCd": { "type": "string", "description": "Postal code (PstCd) - Identifier used by postal services to identify postal zones or geographic areas", "example": "12345" }, "TwnNm": { "type": "string", "description": "Town name (TwnNm) - Name of the town or city", "example": "Springfield" }, "TwnLctnNm": { "type": "string", "description": "Town location name (TwnLctnNm) - Name that identifies a subdivision within a town or city", "example": "Downtown" }, "DstrctNm": { "type": "string", "description": "District name (DstrctNm) - Name that identifies a territorial division or district", "example": "Central District" }, "CtrySubDvsn": { "type": "string", "description": "Country subdivision (CtrySubDvsn) - State, province, or region within a country", "example": "CA" }, "Ctry": { "type": "string", "description": "Country (Ctry) - Country code in ISO 3166-1 alpha-2 format", "example": "US" } }, "description": "ISO 20022 address elements containing structured address components according to PostalAddress27" }, "ISO20022Format": { "type": "object", "properties": { "address": { "description": "Postal address in ISO 20022 format", "allOf": [ { "$ref": "#/components/schemas/ISO20022Address" } ] } }, "description": "ISO 20022 formatted address response following the PostalAddress27 structure" }, "Locale": { "title": "Locale", "type": "object", "properties": { "language": { "type": "string", "description": "The ISO 639 language code.", "example": "en" }, "script": { "type": "string", "description": "The ISO 15924 script code.", "example": "Latn" }, "country": { "type": "string", "description": "The ISO 3166 country code.", "example": "US" }, "variant": { "type": "string", "description": "The variant code for the locale.", "example": "POSIX" }, "unicodeLocaleAttributes": { "type": "array", "description": "The Unicode locale attributes.", "example": [ "attribute1", "attribute2" ], "items": { "type": "string" } }, "unicodeLocaleKeys": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The Unicode locale keys.", "example": { "nu": "thai" } }, "extensionKeys": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The extension keys.", "example": { "x": "private-use" } } }, "description": "Represents a locale with language, script, country, and variant information." }, "Location": { "type": "object", "properties": { "explanation": { "description": "location quality and precision", "allOf": [ { "$ref": "#/components/schemas/LocationExplanation" } ] }, "feature": { "description": "SimpleFeature has geometry and additional properties", "allOf": [ { "$ref": "#/components/schemas/SimpleFeature" } ] } }, "description": "Describes the location type and coordinates" }, "LocationDescriptionTypes": { "type": "string", "description": "Location description types", "example": "STREET_BLOCK", "enum": [ "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" ] }, "LocationDesignationTypes": { "type": "string", "description": "Location designation types", "example": "CENTROID", "enum": [ "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" ] }, "LocationDetail": { "required": [ "country", "latitude", "longitude" ], "type": "object", "properties": { "addressId": { "type": "string", "description": "Address Id for the request", "example": "1" }, "longitude": { "type": "number", "description": "longitude (x)", "format": "double", "example": -73.704719 }, "latitude": { "type": "number", "description": "latitude (y)", "format": "double", "example": 42.682251 }, "country": { "type": "string", "description": "Name of country in ISO 3166-1 Alpha-2 or Alpha-3 format, or a common name of the country", "example": "USA" } }, "description": "List of object contains country and coordinates" }, "LocationExplanation": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/LocationType" }, "description": { "$ref": "#/components/schemas/LocationDescriptionTypes" }, "designation": { "$ref": "#/components/schemas/LocationDesignationTypes" }, "additionalMetadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Any additional metadata about the location", "example": { "SOURCE": "PRECISELY" } } }, "description": "Provides location quality and precision" }, "LocationType": { "type": "string", "description": "Location type", "example": "ADDRESS_POINT", "enum": [ "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" ] }, "LookupKeyType": { "type": "string", "description": "ID lookup key type", "example": "PB_KEY", "enum": [ "PB_KEY", "GNAF_PID", "UDPRN", "UPRN", "EIR_CODE" ] }, "LookupRequest": { "required": [ "keys" ], "type": "object", "properties": { "keys": { "minItems": 1, "type": "array", "description": "list of lookup requests", "items": { "$ref": "#/components/schemas/LookupSingleRequest" } } }, "description": "Request for ID lookup", "allOf": [ { "$ref": "#/components/schemas/BaseRequest" } ] }, "LookupResponse": { "type": "object", "properties": { "responses": { "type": "array", "description": "list of lookup responses", "items": { "$ref": "#/components/schemas/Response" } } }, "description": "Response for ID lookup" }, "LookupSingleRequest": { "required": [ "country", "key", "type" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/LookupKeyType" }, "country": { "required": [ "true" ], "type": "string", "description": "Name of country in ISO 3166-1 Alpha-2 or Alpha-3 format, or a common name of the country", "example": "USA" }, "key": { "required": [ "true" ], "type": "string", "description": "Value for the given Key", "example": "P00003PZZOIE" } }, "description": "LookupSingleRequest to be processed" }, "MatchDescription": { "type": "object", "properties": { "label": { "type": "string", "description": "Label for matching", "example": "streetName" }, "matchType": { "type": "string", "description": "EXACT, PARTIAL, ALIAS_EXACT, ALIAS_PARTIAL, ADDED, REMOVED, NONE", "example": "EXACT" }, "returnType": { "type": "string", "description": "INPUT, PREFERRED, ALIAS, PARTIAL, NONE", "example": "INPUT" }, "matchedSubstring": { "type": "string", "description": "For the Predict service, returns the portion of the input that matched against the output.", "example": "350 Jordan" } }, "description": "Indicates the level of matching" }, "MatchType": { "type": "string", "description": "Match type", "example": "STREET", "enum": [ "ADDRESS", "STREET", "ADMIN", "POBOX", "POI", "NOMATCH" ] }, "ParsedAddress": { "type": "object", "properties": { "score": { "type": "integer", "description": "Score of parsed address", "format": "int32", "example": 0 }, "classifications": { "type": "array", "description": "list the parsed address fields", "items": { "$ref": "#/components/schemas/ParsedFieldClassification" } } }, "description": "Parsed address elements" }, "ParsedFieldClassification": { "type": "object", "properties": { "from": { "type": "string", "description": "from", "example": "\"\"" }, "label": { "type": "string", "description": "label", "example": "street" }, "value": { "type": "string", "description": "value", "example": "DISTRICT" }, "start": { "type": "integer", "description": "start", "format": "int32", "example": 0 }, "end": { "type": "integer", "description": "end", "format": "int32", "example": 0 } }, "description": "Details for parsed address" }, "PredictionResponse": { "type": "object", "properties": { "errorMessage": { "type": "string", "description": "Error message from the underlying service", "example": "Not able to identify ABC country" }, "status": { "$ref": "#/components/schemas/Status" }, "predictions": { "type": "array", "description": "List of prediction results", "items": { "$ref": "#/components/schemas/PredictionResult" } } }, "description": "Prediction response for request" }, "PredictionResult": { "type": "object", "properties": { "prediction": { "type": "string", "description": "All components of the address, formatted to the country's standard, on one line", "example": "350 Jordan Ave, Montoursville, PA 17754" }, "distance": { "description": "distance of address from the origin point of request.", "allOf": [ { "$ref": "#/components/schemas/Distance" } ] } }, "description": "Prediction Results processed for request", "allOf": [ { "$ref": "#/components/schemas/Result" } ] }, "Preferences": { "type": "object", "properties": { "maxResults": { "type": "integer", "description": "The maximum number of candidates to return. Default = 1.", "format": "int32", "example": 1 }, "returnAllInfo": { "type": "boolean", "description": "Specifies whether to return all available information for each candidate.", "example": true }, "factoryDescription": { "description": "description of address processor to process the request.", "allOf": [ { "$ref": "#/components/schemas/FactoryDescription" } ] }, "customPreferences": { "type": "object", "additionalProperties": { "type": "string" }, "description": "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.", "example": { "DATA_OPTION": "PREMIUM" } }, "clientLocale": { "title": "Locale", "description": "Specifies the locale value. For example, specify \"th\" for the Thai language.", "allOf": [ { "$ref": "#/components/schemas/Locale" } ] }, "clientCoordSysName": { "type": "string", "description": "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.", "example": "EPSG:4326" }, "distance": { "description": "distance the defined search radius (default is 5 meters)..", "allOf": [ { "$ref": "#/components/schemas/Distance" } ] }, "streetOffset": { "description": "streetOffset specifies the offset distance from the street segments to use in street-level geocoding (Default 5 meters).", "allOf": [ { "$ref": "#/components/schemas/Distance" } ] }, "cornerOffset": { "description": "Specifies the distance to offset the street end points in street-level matching (default is 7 meters).", "allOf": [ { "$ref": "#/components/schemas/Distance" } ] }, "fallbackToGeographic": { "type": "boolean", "description": "Specifies whether to attempt to determine a geographic centroid when an address-level geocode cannot be determined. Optional.", "example": false }, "fallbackToPostal": { "type": "boolean", "description": "Specifies whether to attempt to determine a post code centroid when an address-level geocode cannot be determined. Optional.", "example": false }, "matchMode": { "type": "string", "description": "Match modes determine the leniency used to make a match between the input address and the reference data.", "example": "EXACT" }, "originXY": { "type": "array", "description": "XY coordinates of the origin address.", "example": [ 0, 0 ], "items": { "type": "number", "format": "double" } }, "returnOfAdditionalFields": { "type": "array", "description": "This lets the user control which additional fields they want to have returned if they do not want to return all info.", "example": [ "RESULT_CODE", "PRECISION_CODE" ], "items": { "type": "string" } } }, "description": "Preferences that will processed with the request" }, "RequestAddress": { "required": [ "country" ], "type": "object", "properties": { "city": { "type": "string", "description": "Specifies a city or town name.", "example": "New York City" }, "street": { "type": "string", "description": "Street name only (no directional or street suffix).", "example": "DISTRICT" }, "admin2": { "type": "string", "description": "The secondary geographic area, typically a county or district.", "example": "Douglas County" }, "placeName": { "type": "string", "description": "If applicable, indicates the name of the candidate's place or building.", "example": "PRIME MINISTER & FIRST LORD OF THE TREASURY" }, "addressNumber": { "type": "string", "description": "House or building number.", "example": "630" }, "suburb": { "type": "string", "description": "Mixed-use or residential area within commuting distance of a city or urban area.", "example": "Manhattan" }, "neighborhood": { "type": "string", "description": "A city subdivision or locality.", "example": "Highlands Ranch" }, "admin1": { "type": "string", "description": "The largest geographic area, typically a state or province.", "example": "New York" }, "postalCode": { "type": "string", "description": "Main postal code.", "example": "80125" }, "floor": { "type": "string", "description": "Each level within a building.", "example": "65" }, "postalCodeExt": { "type": "string", "description": "Secondary postal code, if one exists. For example, in the US, a ZIP+4 is 80125-8012.", "example": "8012" }, "room": { "type": "string", "description": "A single room within a building.", "example": "A1" }, "borough": { "type": "string", "description": "Unit of local government or other administrative subdivision.", "example": "Vazira or Manhattan" }, "unit": { "type": "string", "description": "The unit number, such as \"3B\".", "example": "3B" }, "unitType": { "type": "string", "description": "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.).", "example": "APT" }, "building": { "type": "string", "description": "A roofed and walled structure built for permanent use.", "example": "Empire State" }, "country": { "type": "string", "description": "Values are based on the ISO 3166-1 standard for country codes (returned in alpha-2, alpha-3, or numeric format).", "example": "USA, US or 840" }, "addressLines": { "type": "array", "description": "Requested address, based on the country's addressing standard.", "example": [ "1700 District Ave #300 Burlington, MA" ], "items": { "type": "string" } } }, "description": "Request address that will be processed" }, "RequestAddressWithId": { "type": "object", "properties": { "addressId": { "type": "string", "description": "Address Id for the request", "example": "1" } }, "description": "Addresses to be processed", "allOf": [ { "$ref": "#/components/schemas/RequestAddress" } ] }, "Response": { "type": "object", "properties": { "addressId": { "type": "string", "description": "Address Id of the response", "example": "1" }, "errorMessage": { "type": "string", "description": "Error message from the underlying service", "example": "Not able to identify ABC country" }, "status": { "$ref": "#/components/schemas/Status" }, "results": { "type": "array", "description": "List of results", "items": { "$ref": "#/components/schemas/Result" } } }, "description": "Responses for address requests" }, "ResponseAddress": { "type": "object", "properties": { "street": { "type": "string", "description": "Street name only (no directional or street suffix).", "example": "DISTRICT" }, "formattedAddress": { "type": "string", "description": "All components of the address, formatted to the country's standard, on one line.", "example": "1700 DISTRICT AVE STE 300, BURLINGTON MA 01803-5231, United States" }, "formattedStreetAddress": { "type": "string", "description": "Street portion of the address, including the directional and street suffix, formatted to the country's standard.", "example": "1700 DISTRICT AVE STE 300" }, "formattedLocationAddress": { "type": "string", "description": "Location portion of the address, formatted to the country's standard.", "example": "BURLINGTON, MA 01803-5231" }, "addressNumber": { "type": "string", "description": "House or building number.", "example": "630" }, "country": { "description": "detail of country based on the ISO 3166-1 standard", "allOf": [ { "$ref": "#/components/schemas/CountryField" } ] }, "admin1": { "description": "Specifies the largest geographic area, typically a state or province", "allOf": [ { "$ref": "#/components/schemas/AdminField" } ] }, "admin2": { "description": "Specifies the secondary geographic area, typically a county or district", "allOf": [ { "$ref": "#/components/schemas/AdminField" } ] }, "city": { "description": "Specifies a city or town name", "allOf": [ { "$ref": "#/components/schemas/AdminField" } ] }, "borough": { "description": "Unit of local government or other administrative subdivision.", "allOf": [ { "$ref": "#/components/schemas/AdminField" } ] }, "neighborhood": { "description": "Specifies a city subdivision or locality.", "allOf": [ { "$ref": "#/components/schemas/AdminField" } ] }, "suburb": { "description": "Mixed-use or residential area within commuting distance of a city or urban area.", "allOf": [ { "$ref": "#/components/schemas/AdminField" } ] }, "postalCode": { "type": "string", "description": "Main postal code.", "example": "80125" }, "postalCodeExt": { "type": "string", "description": "Secondary postal code, if one exists. For example, in the US, a ZIP+4 is 80125-8012.", "example": "8012" }, "placeName": { "type": "string", "description": "If applicable, indicates the name of the candidate's place or building.", "example": "PRIME MINISTER & FIRST LORD OF THE TREASURY" }, "building": { "type": "string", "description": "A roofed and walled structure built for permanent use.", "example": "Empire State" }, "floor": { "type": "string", "description": "Each level within a building.", "example": "65" }, "room": { "type": "string", "description": "A single room within a building.", "example": "A1" }, "unit": { "type": "string", "description": "The unit number, such as \"3B\".", "example": "3B" }, "unitType": { "type": "string", "description": "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.).", "example": "STE" } }, "description": "Displays components of the address" }, "ResponseOptions": { "type": "object", "properties": { "includeOfficialDescription": { "type": "boolean", "description": "Whether to include official description in output", "example": true } }, "description": "Options for controlling response details" }, "Result": { "type": "object", "properties": { "score": { "type": "integer", "description": "Provides a number from 0-100 to indicate how much the input was changed in order to match to the output candidate.", "format": "int32", "example": 95 }, "addressLines": { "type": "array", "description": "Displays multiple formatted lines to support the postal standard of a given country.", "example": [ "350 Jordan Ave", "Montoursville PA 17754" ], "items": { "type": "string" } }, "explanation": { "description": "details the level of matching for each component of an address", "allOf": [ { "$ref": "#/components/schemas/Explanation" } ] }, "address": { "description": "response address", "allOf": [ { "$ref": "#/components/schemas/ResponseAddress" } ] }, "location": { "description": "Describes the location details", "allOf": [ { "$ref": "#/components/schemas/Location" } ] }, "customFields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Returns additional information about the address.", "example": { "NAME_SHORT": "DISTRICT", "PLACE": "2509875", "CITY_SHORT": "BURLINGTON" } }, "parsed": { "type": "array", "description": "list the details of parsed request address", "example": [ { "score": 0, "classifications": [ { "label": "street", "value": "DISTRICT" } ] } ], "items": { "$ref": "#/components/schemas/ParsedAddress" } }, "iso20022": { "description": "Address formatted according to ISO 20022 PostalAddress27 standard", "allOf": [ { "$ref": "#/components/schemas/ISO20022Format" } ] } }, "description": "Processed Result" }, "ReverseGeocodeRequest": { "required": [ "locations" ], "type": "object", "properties": { "locations": { "minItems": 1, "type": "array", "description": "list of locations for reverse geocode", "items": { "$ref": "#/components/schemas/LocationDetail" } } }, "description": "Request for reverse-geocode", "allOf": [ { "$ref": "#/components/schemas/BaseRequest" } ] }, "ReverseGeocodeResponse": { "type": "object", "properties": { "responses": { "type": "array", "description": "list of reverse geocode responses", "items": { "$ref": "#/components/schemas/Response" } } }, "description": "Response for reverse-geocode" }, "SimpleFeature": { "type": "object", "properties": { "geometry": { "description": "Provides the geometry details", "allOf": [ { "$ref": "#/components/schemas/Geometry" } ] }, "properties": { "type": "object", "additionalProperties": { "type": "string" }, "description": "crsName - The coordinate reference system (CRS) used for the candidate's geocode. Expressed in epsg:nnnn format; the default is epsg:4326", "example": { "crsName": "epsg:4326" } }, "type": { "type": "string", "description": "Feature", "example": "Feature" } }, "description": "SimpleFeature object with geometry and additional properties" }, "Status": { "type": "string", "description": "Status", "example": "OK", "enum": [ "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" ] }, "VerifyRequest": { "required": [ "addresses" ], "type": "object", "properties": { "addresses": { "minItems": 1, "type": "array", "description": "list of addresses for verify", "items": { "$ref": "#/components/schemas/RequestAddressWithId" } } }, "description": "Request for address verification", "allOf": [ { "$ref": "#/components/schemas/BaseRequest" } ] }, "VerifyResponse": { "type": "object", "properties": { "responses": { "type": "array", "description": "list of verify responses", "items": { "$ref": "#/components/schemas/Response" } } }, "description": "Response for address verification" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "description": "Pass the value in the following format: Apikey .", "name": "Authorization", "in": "header" }, "bearerAuth": { "type": "http", "description": "Pass the value as JWT Bearer Token.", "scheme": "bearer" } } } }