{
"openapi": "3.0.1",
"info": {
"title": "Address Fit API",
"description": "The Address Fit API takes a single street address line, together with a country\ncode and a maximum allowed length, and returns a version of the street that has\nbeen progressively abbreviated (using country-specific abbreviation rules) until\nit fits within the requested length, or reports why it could not do so.\n\n\n Error Codes
\n\n| Error Code | Description\n|---------------|-------------------------------------------\n| DIS-1001 | Unauthorized\n| DIS-1002 | You do not have permission to access this API\n| DIS-1003 | Issue with internal services. Please try again after sometime\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-1015 | countryCode is required\n| DIS-LI-1016 | countryCode is not supported, or not a valid alpha-3 country code\n| DIS-LI-1018 | Request body is invalid\n| DIS-LI-1019 | Request body is not specified in the request\n| DIS-LI-1058 | street is required\n| DIS-LI-1059 | maxLength must be between 1 and 100\n\n \n",
"version": "1.0"
},
"servers": [
{
"url": "https://api.cloud.precisely.com"
}
],
"tags": [
{
"name": "Address Fit",
"description": "Fits a street address into a country-specific maximum length."
}
],
"paths": {
"/v1/address-fit": {
"post": {
"tags": [
"Address Fit"
],
"summary": "Fits a street address into a country-specific maximum length.",
"description": "Fits a single street address line into the requested maximum length for the given\ncountry. The street is progressively abbreviated using country-specific abbreviation\nrules (e.g. \"Street\" -> \"St\", \"Apartment\" -> \"Apt\") until it fits, or until no further\nabbreviation is possible.\n\nThe `result.status` field indicates the outcome:\n- `OK` — the processed street fits within `maxLength`. `warnings` is omitted.\n- `WARN` — the street could not be shortened enough to fit within `maxLength`, so the\n best-effort abbreviated street is returned along with a non-empty `warnings` list.\n\nIf the request itself is invalid (missing/blank street, unsupported or unrecognised\ncountryCode, out-of-range maxLength, malformed JSON, etc.) no `result` is returned;\ninstead a 4xx/5xx response with a non-empty `errors` list is returned. See the Error\nCodes table above for the full list.\n",
"operationId": "fit",
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"description": "Optional client-supplied correlation id, echoed back in logs to help trace a single\nrequest end-to-end. If omitted, the request is still processed normally.\n",
"schema": {
"type": "string"
},
"example": "123e4567-e89b-12d3-a456-426614174000"
}
],
"requestBody": {
"description": "Address Fit request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressFitRequest"
},
"examples": {
"example": {
"value": {
"street": "123 Main Street Apartment",
"countryCode": "USA",
"maxLength": 15
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Street address fitted successfully (see result.status for OK/WARN)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressFitResponse"
},
"examples": {
"OK": {
"value": {
"response": {
"status": "OK",
"result": {
"countryCode": "USA",
"maxLength": 15,
"originalStreet": "123 Main Street Apartment",
"processedStreet": "123 MAIN ST APT",
"originalLength": 25,
"finalLength": 15
}
}
}
},
"WARN": {
"value": {
"response": {
"status": "WARN",
"result": {
"countryCode": "GBR",
"maxLength": 12,
"originalStreet": "123 Some Long Street Name",
"processedStreet": "123 Some Long St",
"originalLength": 25,
"finalLength": 16,
"warnings": [
"Not able to achieve desired max length"
]
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid request for Address Fit API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressFitErrorResponse"
},
"examples": {
"Missing countryCode": {
"value": {
"errors": [
{
"code": "DIS-LI-1015",
"detail": "countryCode is required"
}
]
}
},
"Unresolvable countryCode": {
"value": {
"errors": [
{
"code": "DIS-LI-1016",
"detail": "countryCode 'XYZ' is not a valid alpha-3 country code"
}
]
}
},
"Unsupported countryCode": {
"value": {
"errors": [
{
"code": "DIS-LI-1016",
"detail": "countryCode is not supported"
}
]
}
},
"Invalid body": {
"value": {
"errors": [
{
"code": "DIS-LI-1018",
"detail": "Request body is invalid"
}
]
}
},
"Missing body": {
"value": {
"errors": [
{
"code": "DIS-LI-1019",
"detail": "Request body is not specified in the request"
}
]
}
},
"Missing street": {
"value": {
"errors": [
{
"code": "DIS-LI-1058",
"detail": "street is required"
}
]
}
},
"Invalid maxLength": {
"value": {
"errors": [
{
"code": "DIS-LI-1059",
"detail": "maxLength must be between 1 and 100"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized: Invalid token for Address Fit API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressFitErrorResponse"
},
"examples": {
"example": {
"value": {
"errors": [
{
"code": "DIS-1001",
"detail": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "Forbidden for Address Fit API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressFitErrorResponse"
},
"examples": {
"example": {
"value": {
"errors": [
{
"code": "DIS-1002",
"detail": "You do not have permission to access this API"
}
]
}
}
}
}
}
},
"429": {
"description": "Too many requests for Address Fit API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressFitErrorResponse"
},
"examples": {
"example": {
"value": {
"errors": [
{
"code": "DIS-1005",
"detail": "Rate limit exceeded"
}
]
}
}
}
}
}
},
"500": {
"description": "Internal server error for Address Fit API",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressFitErrorResponse"
},
"examples": {
"example": {
"value": {
"errors": [
{
"code": "DIS-1003",
"detail": "Issue with internal services. Please try again after sometime"
}
]
}
}
}
}
}
}
},
"security": [
{
"bearerAuth": []
},
{
"ApiKeyAuth": []
}
]
}
}
},
"components": {
"schemas": {
"AddressFitErrorDetail": {
"required": [
"code",
"detail"
],
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "The DIS error code identifying the specific failure. See the Error Codes table for the full list.",
"example": "DIS-LI-1015"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the failure.",
"example": "countryCode is required"
}
},
"description": "A single error detail describing one reason the request could not be processed."
},
"AddressFitErrorResponse": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"description": "One or more errors describing why the request failed. Always non-empty on an error response.",
"items": {
"$ref": "#/components/schemas/AddressFitErrorDetail"
}
}
},
"description": "Error response envelope returned for any non-2xx Address Fit API response."
},
"AddressFitRequest": {
"required": [
"countryCode",
"street"
],
"type": "object",
"properties": {
"street": {
"maxLength": 500,
"minLength": 1,
"type": "string",
"description": "The street address line to fit. Must be non-blank and at most 500 characters.",
"example": "123 Main Street Apartment",
"x-size-message": "street must be at most 500 characters"
},
"countryCode": {
"minLength": 1,
"type": "string",
"description": "Country code identifying which country-specific abbreviation rules to apply. Must resolve to a valid ISO 3166-1 alpha-3 code (e.g. \"GBR\", \"USA\"); values that cannot be resolved to a supported alpha-3 code, or that resolve to a country not yet supported by this API, are rejected (see DIS-LI-1016 in the Error Codes table above).",
"example": "USA",
"x-size-message": "countryCode is required"
},
"maxLength": {
"maximum": 100,
"minimum": 1,
"type": "integer",
"description": "Maximum allowed length (in characters) for the processed street. If omitted, the country's default maximum length is used.",
"format": "int32",
"example": 15,
"x-maximum-message": "maxLength must be at most 100",
"x-minimum-message": "maxLength must be at least 1"
}
},
"description": "Address Fit request: a single street address line to fit into a country-specific maximum length."
},
"AddressFitResponse": {
"type": "object",
"properties": {
"response": {
"description": "The fitted address result.",
"allOf": [
{
"$ref": "#/components/schemas/AddressFitResponse.AddressFitResponseBody"
}
]
}
},
"description": "Address Fit response envelope."
},
"AddressFitResponse.AddressFitResponseBody": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "`OK` if the processed street fits within maxLength; `WARN` if it could not be shortened enough and the best-effort result is returned with warnings.",
"example": "OK",
"enum": [
"OK",
"WARN"
]
},
"result": {
"description": "The fitted address details.",
"allOf": [
{
"$ref": "#/components/schemas/AddressFitResult"
}
]
}
},
"description": "Outcome status and the fitted address result."
},
"AddressFitResult": {
"type": "object",
"properties": {
"countryCode": {
"type": "string",
"description": "ISO 3166-1 alpha-3 country code the street was fitted for.",
"example": "GBR"
},
"maxLength": {
"type": "integer",
"description": "The maximum length that was applied (either the requested value, or the country's default if none was requested).",
"format": "int32",
"example": 16
},
"originalStreet": {
"type": "string",
"description": "The original, unmodified street address line as submitted in the request.",
"example": "123 Some Long Street Name"
},
"processedStreet": {
"type": "string",
"description": "The abbreviated street address line, after applying country-specific abbreviation rules.",
"example": "123 Some Long St"
},
"originalLength": {
"type": "integer",
"description": "Character length of originalStreet.",
"format": "int32",
"example": 25
},
"finalLength": {
"type": "integer",
"description": "Character length of processedStreet.",
"format": "int32",
"example": 16
},
"warnings": {
"type": "array",
"description": "Present only when status is WARN: explains why processedStreet still exceeds maxLength. Omitted entirely (not an empty array) when status is OK.",
"example": [
"Not able to achieve desired max length"
],
"items": {
"type": "string"
}
}
},
"description": "The result of fitting a single street address into the requested country-specific maximum length."
}
},
"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"
}
}
}
}