{
"openapi": "3.0.3",
"info": {
"title": "Address Parser API",
"description": "The Address Parser API processes single-line addresses and breaks them into structured components.\n\nError Codes
\nAPIs may return the following error codes:\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 permanently exhausted. No further requests allowed for trial users |\n| DIS-1008 | Invalid request ID, maximum allowed length is 38 characters |\n| DIS-1009 | Access blocked due to too many failed attempts. Please try again later. |\n| DIS-1010 | Workspace has expired |\n| DIS-AP-1001 | Request is not valid |\n| DIS-AP-1002 | Batch size must not exceed 10 |\n \n",
"version": "v1.0.0"
},
"tags": [
{
"name": "Address Parser",
"description": "Operations related to parsing addresses into structured components."
}
],
"servers": [
{
"url": "https://api.cloud.precisely.com"},{"url":"https://api.gb1.cloud.precisely.com"
}
],
"paths": {
"/v1/address/parse": {
"post": {
"tags": [
"Address Parser"
],
"summary": "Parse Address",
"description": "Parses a single-line address into its components.",
"operationId": "parse",
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"description": "The X-Request-Id header is optional but helpful for tracking requests. \nIt acts as a unique identifier for troubleshooting and debugging issues effectively.\nMaximum length: 38 characters.\n",
"example": "3cf82271-835d-40c3-b425-7550166eb1e5",
"required": false,
"schema": {
"type": "string",
"example": "3cf82271-385d-40c3-b425-7550166eb1e5"
}
}
],
"requestBody": {
"description": "Input for address parsing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressInfo"
},
"examples": {
"example": {
"value": {
"address": "1700 district ave #300 burlington, ma"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Address successfully parsed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ParsedAddressResponse"
},
"examples": {
"example": {
"value": {
"response": {
"status": "OK",
"address": {
"addressNumber": "1700",
"admin1": "ma",
"city": "burlington",
"street": "district ave",
"unit": "#300"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid Request for address parser API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"example": {
"value": {
"id": "afdb86d9-8f6d-4b07-9b2c-6ced9df45d8d",
"errors": [
{
"code": "DIS-AP-1001",
"detail": "Request is not valid"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized: Invalid token for address parser API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"example": {
"value": {
"id": "ad45c1aded938181a05f256e5a1b594d",
"errors": [
{
"code": "DIS-1001",
"detail": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "Forbidden for address parser API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"example": {
"value": {
"id": "9c260ad088c2d64a9f2dd17b2cebb7d1",
"errors": [
{
"code": "DIS-1002",
"detail": "You do not have permission to access this API"
}
]
}
}
}
}
}
},
"429": {
"description": "Too many requests for address parser API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"example": {
"value": {
"id": "754b7151562ce0f01b6bc4521990fe4a",
"errors": [
{
"code": "DIS-1005",
"detail": "Rate limit exceeded"
}
]
}
}
}
}
}
},
"500": {
"description": "Internal server error for address parser API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"example": {
"value": {
"id": "557348c51c55b3bc21f13410885bb41e",
"errors": [
{
"code": "DIS-1003",
"detail": "Issue with internal services. Please try again after"
}
]
}
}
}
}
}
}
},
"security": [
{
"bearerAuth": []
},
{
"ApiKeyAuth": []
}
]
}
},
"/v1/address/parse/batch": {
"post": {
"tags": [
"Address Parser"
],
"summary": "Parse Address Batch",
"description": "Parses a batch of up to 10 single-line addresses into components.",
"operationId": "parseBatch",
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"description": "The X-Request-Id header is optional but helpful for tracking batch requests.\nActs as a unique identifier for troubleshooting and debugging.\nMaximum length: 38 characters.\n",
"example": "3cf82271-385d-40c3-b425-7550144eb1e5",
"required": false,
"schema": {
"type": "string",
"example": "3cf82271-385d-40c3-b425-7550144eb1e5"
}
}
],
"requestBody": {
"description": "Input for batch address parsing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressInfoBatch"
},
"examples": {
"example": {
"value": {
"addresses": [
{
"id": "1",
"address": "1700 district ave #300 burlington, ma"
},
{
"id": "2",
"address": "170 district ave burlington, ma"
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Batch addresses parsed successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ParsedAddressResponses"
},
"examples": {
"example": {
"value": {
"responses": [
{
"id": "1",
"status": "OK",
"address": {
"addressNumber": "1700",
"admin1": "ma",
"city": "burlington",
"street": "district ave",
"unit": "#300"
}
},
{
"id": "2",
"status": "OK",
"address": {
"addressNumber": "170",
"admin1": "ma",
"city": "burlington",
"street": "district ave"
}
}
]
}
}
}
}
}
},
"206": {
"description": "Batch address parsed partially",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ParsedAddressResponses"
},
"examples": {
"example": {
"value": {
"responses": [
{
"id": "1",
"status": "OK",
"address": {
"addressNumber": "1700",
"admin1": "ma",
"city": "burlington",
"street": "district ave",
"unit": "#300"
}
},
{
"id": "2",
"code": "DIS-AP-1001",
"detail": "Request is not valid"
}
]
}
}
}
}
}
},
"400": {
"description": "Invalid Request for batch address parser API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"example": {
"value": {
"id": "439a993a-8306-4a89-9c07-33280d21a7f7",
"errors": [
{
"code": "DIS-AP-1001",
"detail": "Request is not valid"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized: Invalid token for batch address parser API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"example": {
"value": {
"id": "ad45c1aded938181a05f256e5a1b594d",
"errors": [
{
"code": "DIS-1001",
"detail": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "Forbidden for batch address parser API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"example": {
"value": {
"id": "9c260ad088c2d64a9f2dd17b2cebb7d1",
"errors": [
{
"code": "DIS-1002",
"detail": "You do not have permission to access this API"
}
]
}
}
}
}
}
},
"413": {
"description": "Request entity too large for batch address parser API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"example": {
"value": {
"id": "6e7774f8-300d-9f82-9d0d-7688027d08c2",
"errors": [
{
"code": "DIS-AP-1002",
"detail": "Batch size must not exceed 10"
}
]
}
}
}
}
}
},
"429": {
"description": "Too many requests for batch address parser API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"example": {
"value": {
"id": "6e5554f8-300d-9f82-9d0d-7688027d08c2",
"errors": [
{
"code": "DIS-1005",
"detail": "Rate limit exceeded"
}
]
}
}
}
}
}
},
"500": {
"description": "Internal server error for batch address parser API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"example": {
"value": {
"id": "557348c51c55b3bc21f13410885bb41e",
"errors": [
{
"code": "DIS-1003",
"detail": "Issue with internal services. Please try again after sometime"
}
]
}
}
}
}
}
},
"503": {
"description": "Batch address parser service unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"example": {
"value": {
"id": "9408ae330240118eb4e83373413ef781",
"errors": [
{
"code": "DIS-1003",
"detail": "Issue with internal services. Please try again after"
}
]
}
}
}
}
}
}
},
"security": [
{
"bearerAuth": []
},
{
"ApiKeyAuth": []
}
]
}
}
},
"components": {
"schemas": {
"AddressInfo": {
"type": "object",
"required": [
"address"
],
"description": "Schema for parsing a single address input into structured components, such as house number, street, and city.",
"properties": {
"id": {
"type": "string",
"description": "An optional ID to map the request payload to the response payload, helpful for batch processing.",
"nullable": true,
"example": "1"
},
"address": {
"type": "string",
"description": "A single-line address string to parse into structured components.",
"example": "1700 district ave #300 burlington, ma"
}
}
},
"AddressInfoBatch": {
"type": "object",
"description": "Schema for parsing a batch of address inputs, each with an optional ID for request-response mapping.",
"required": [
"addresses"
],
"properties": {
"addresses": {
"type": "array",
"minItems": 1,
"description": "A list of addresses, each with an optional ID for tracking purposes.",
"items": {
"$ref": "#/components/schemas/AddressInfo"
}
}
}
},
"ErrorDetail": {
"type": "object",
"description": "Schema detailing an error encountered during API processing.",
"required": [
"detail"
],
"properties": {
"code": {
"type": "string",
"description": "A unique code identifying the specific error.",
"example": "DIS-1001"
},
"detail": {
"type": "string",
"description": "A descriptive message providing additional context about the error.",
"example": "Unauthorized"
}
}
},
"ErrorResponse": {
"type": "object",
"description": "Schema representing a response containing error details.",
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for tracking the error response.",
"example": "ad45c1aded938181a05f256e5a1b594d"
},
"errors": {
"type": "array",
"description": "A list of error details encountered during the request.",
"items": {
"$ref": "#/components/schemas/ErrorDetail"
}
}
}
},
"ParsedAddress": {
"type": "object",
"description": "Schema representing a parsed address, including structured components and error details, if any.",
"properties": {
"id": {
"type": "string",
"description": "Optional ID for mapping parsed addresses to their corresponding requests.",
"nullable": true,
"example": "1"
},
"status": {
"type": "string",
"description": "The parsing status (e.g., \"OK\" for success).",
"nullable": true,
"example": "OK"
},
"code": {
"type": "string",
"description": "Error code for failed parsing, providing context for the error.",
"nullable": true,
"example": "DIS-AP-1001"
},
"detail": {
"type": "string",
"description": "A detailed error message for failed parsing.",
"nullable": true,
"example": "Request is not valid"
},
"address": {
"type": "object",
"description": "Schema representing a single address input with structured components for house or building details, geographic areas, and other optional details.",
"example": {
"addressNumber": "1700",
"street": "district ave",
"admin1": "ma",
"city": "burlington",
"suburb": "north suburb",
"postalCode": "01803",
"placeName": "Corporate Plaza",
"floor": "3rd Floor",
"unit": "#300"
},
"properties": {
"addressNumber": {
"type": "string",
"nullable": true,
"description": "The house or building number.",
"example": "1700"
},
"street": {
"type": "string",
"nullable": true,
"description": "The street name where the address is located.",
"example": "district ave"
},
"admin1": {
"type": "string",
"nullable": true,
"description": "The primary geographic area, such as a state.",
"example": "ma"
},
"city": {
"type": "string",
"nullable": true,
"description": "The city or town of the address.",
"example": "burlington"
},
"suburb": {
"type": "string",
"nullable": true,
"description": "The suburb or secondary geographic area, if applicable.",
"example": "north suburb"
},
"postalCode": {
"type": "string",
"nullable": true,
"description": "The main postal code for the address.",
"example": "01803"
},
"placeName": {
"type": "string",
"nullable": true,
"description": "The name of a candidate's place or building, if applicable.",
"example": "Corporate Plaza"
},
"floor": {
"type": "string",
"nullable": true,
"description": "The level or floor within a building.",
"example": "3rd Floor"
},
"unit": {
"type": "string",
"nullable": true,
"description": "The unit or suite number within a building.",
"example": "#300"
}
}
}
}
},
"ParsedAddressResponse": {
"type": "object",
"description": "Schema for a response containing parsed address details, including parsing status and structured address components.",
"properties": {
"response": {
"description": "Contains the parsed address details, including the structured components and the parsing status.",
"allOf": [
{
"$ref": "#/components/schemas/ParsedAddress"
}
]
}
}
},
"ParsedAddressResponses": {
"type": "object",
"description": "Schema for a collection of parsed address responses, including successes and failures.",
"properties": {
"responses": {
"type": "array",
"description": "A list of parsed addresses, including structured details or error information.",
"items": {
"$ref": "#/components/schemas/ParsedAddress"
}
}
}
}
},
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"description": "Pass the value in the format: Apikey ."
},
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Provide the value as a JWT Bearer Token."
}
}
}
}