Discrepancy Between Method Documentation and API Response for Address Validation

[Leggendario12]

I've encountered a discrepancy between the expected results described in the documentation for the validate_addresses method and the actual response received from the API. The method's documentation suggests a specific structure for the returned data, but the actual data received differs notably in format and content.

The validate_addresses method in our system is documented to cross-reference addresses against multiple databases for validation and returns a structured response with details on validated and normalized addresses.

    def validate_addresses(
        self, address: List[Dict[str, Any]], config: Union[str, Dict[str, Any]] = None
    ) -> Dict[str, Any]:
        """
        Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address
        correction surcharges. ShipEngine cross references multiple databases to validate addresses and identify
        potential deliverability issues.
        See: https://shipengine.github.io/shipengine-openapi/#operation/validate_address

        :param List[Dict[str, Any]] address: A list containing the address(es) to be validated.
        :param Union[str, Dict[str, Any], ShipEngineConfig] config: Method level configuration to set new values
        for properties of the global ShipEngineConfig object.
        :returns: Dict[str, Any]: The response from ShipEngine API including the validated and normalized address.
        """
        config = self.config.merge(new_config=config)
        return self.client.post(
            endpoint=Endpoints.ADDRESSES_VALIDATE.value, params=address, config=config
        )

Example Response:

[
    {
        "matched_address": {
            "address_line1": "3800 N LAMAR BLVD STE 220",
            "address_line2": "",
            "address_line3": None,
            "address_residential_indicator": "no",
            "city_locality": "AUSTIN",
            "company_name": None,
            "country_code": "US",
            "name": "SHIPENGINE",
            "phone": "1-123-123-1234",
            "postal_code": "78756-0003",
            "state_province": "TX",
        },
        "messages": [],
        "original_address": {
            "address_line1": "3800 N Lamar Blvd",
            "address_line2": "ste 220",
            "address_line3": None,
            "address_residential_indicator": "unknown",
            "city_locality": "Austin",
            "company_name": None,
            "country_code": "US",
            "name": "ShipEngine",
            "phone": "1-123-123-1234",
            "postal_code": "78756",
            "state_province": "TX",
        },
        "status": "verified",
    },
    {
        "matched_address": {
            "address_line1": "3800 N LAMAR BLVD STE 220",
            "address_line2": "",
            "address_line3": "2ND FLOOR",
            "address_residential_indicator": "no",
            "city_locality": "AUSTIN",
            "company_name": None,
            "country_code": "US",
            "name": "SHIPENGINE",
            "phone": "1-123-123-1234",
            "postal_code": "78756-0003",
            "state_province": "TX",
        },
        "messages": [],
        "original_address": {
            "address_line1": "3800 N Lamar Blvd",
            "address_line2": "ste 220",
            "address_line3": "2nd Floor",
            "address_residential_indicator": "unknown",
            "city_locality": "Austin",
            "company_name": None,
            "country_code": "US",
            "name": "ShipEngine",
            "phone": "1-123-123-1234",
            "postal_code": "78756",
            "state_province": "TX",
        },
        "status": "verified",
    },
]

Which makes the return type to be List[Dict[str, Any]]