Address validation

Normalize an address and check its postcode, PO Box status and phone number.

geo.validate Stable point

How to call it

Request schema

Generated from the same validation rules the endpoint runs, so a field cannot be documented without being validated.

POST /v1/geo/validate

{
    "type": "object",
    "properties": {
        "address1": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 255
        },
        "address2": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 255
        },
        "city": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 120
        },
        "country": {
            "type": "string",
            "maxLength": 120
        },
        "phone": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 40
        },
        "postcode": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 32
        },
        "province": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 120
        }
    },
    "additionalProperties": false,
    "required": [
        "country"
    ]
}

Request example

{
    "address1": "1000 Rue De La Gauchetière O",
    "city": "Montreal",
    "province": "QC",
    "country": "CA",
    "postcode": "H3B 4W5",
    "phone": "514 555 0134"
}

Response

What a successful call returns: the schema of `data` and `meta`, with a description of each field, followed by an example response from a real call.

POST /v1/geo/validate

Response schema

{
    "description": "Whether an address is deliverable as written: the postcode format of the country, PO Box detection and phone parsing, with the address normalized.",
    "data": {
        "type": "object",
        "properties": {
            "valid": {
                "type": "boolean",
                "description": "True when `issues` is empty."
            },
            "issues": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "field": {
                            "type": "string",
                            "description": "The request field at fault."
                        },
                        "code": {
                            "type": "string",
                            "enum": [
                                "POSTCODE_FORMAT",
                                "PO_BOX",
                                "PHONE_UNPARSEABLE"
                            ]
                        },
                        "message": {
                            "type": "string"
                        }
                    }
                }
            },
            "normalized": {
                "type": "object",
                "description": "The address as sent, tidied. Fields not sent are left out.",
                "properties": {
                    "address_1": {
                        "type": "string"
                    },
                    "address_2": {
                        "type": "string"
                    },
                    "city": {
                        "type": "string"
                    },
                    "province": {
                        "type": "string"
                    },
                    "country": {
                        "type": "string",
                        "description": "ISO 3166-1 alpha-2."
                    },
                    "postcode": {
                        "type": "string",
                        "description": "Upper case, without spaces."
                    },
                    "phone": {
                        "type": "string",
                        "description": "E.164, when a phone was sent and could be parsed."
                    }
                }
            },
            "checks": {
                "type": "object",
                "properties": {
                    "postcode_format": {
                        "type": [
                            "boolean",
                            "null"
                        ],
                        "description": "True when the postcode matches the country's format; null when the country has no known format or no postcode was sent."
                    },
                    "po_box": {
                        "type": "boolean",
                        "description": "True when the address is a PO Box."
                    }
                }
            }
        }
    }
}

Response example

{
    "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
    "capability": "geo.validate",
    "billing": {
        "unit": "point",
        "quantity": 1,
        "counted": true
    },
    "data": {
        "valid": true,
        "issues": [],
        "normalized": {
            "address_1": "1000 Rue De La Gauchetière O",
            "city": "Montreal",
            "province": "QC",
            "country": "CA",
            "postcode": "H3B4W5",
            "phone": "+15145550134"
        },
        "checks": {
            "postcode_format": true,
            "po_box": false
        }
    }
}

What it costs

One address or coordinate.

Every billable response carries a billing block with the unit, the quantity and how the quantity was derived.

Errors it can return