Location main address validation rules for structured address fields and geographic accuracy

Change Detection

SuspiciousRemovalOfFullAddress

Definition	Severity	API	Sample	Mode
Validate that fullAddress is present when previously submitted

SuspiciousRemovalOfStructuredAddress

Definition	Severity	API	Sample	Mode
Validate that structuredAddress is present when previously submitted

Containment

LocationContainedByUnsupportedArea

Preconditions
Organization type is location owner or unverified agency

Definition	Severity	API	Sample	Mode
Validate that the geocode calculated for a structuredAddress or fullAddress is not contained by an unsupported area

Example Validation Report

{
  "code": "VALIDATION__LocationContainedByUnsupportedArea",
  "severity": "WARNING",
  "message": "Support in area not available"
}

LocationSupportInAreaIsConditional

Preconditions
Organization type is location owner or unverified agency

Definition	Severity	API	Sample	Mode
Validate that the geocode calculated for a structuredAddress or fullAddress is not contained by a conditionally allowed area

Example Validation Report

{
  "code": "VALIDATION__LocationSupportInAreaIsConditional",
  "severity": "WARNING",
  "message": "Support in area is conditional"
}

Cross-feature

ImprobableDistanceBetweenAddressGeocodeAndDisplayPoint

Preconditions
fullAddress or structuredAddress (or both) is present and at least one is successfully geocoded
displayPoint is present

Definition	Severity	API	Sample	Mode
Validate that the distance between either the fullAddress or structuredAddress geocode and the display point coordinates does not exceed a maximum distance (1000 meters)

note

When both fullAddress and structuredAddress are present, one of the two geocodes must not exceed the maximum distance

Example Validation Report

{
  "code": "VALIDATION__ImprobableDistanceBetweenAddressGeocodeAndDisplayPoint",
  "severity": "WARNING",
  "message": "Distance between address geocode and display point coordinates exceeds threshold",
  "details": {
    "createdDate": "2026-06-10T11:36:02.00Z",
    "submitted": [
      {
        "field": "$.locationDetails.displayPoint",
        "value": {
          "displayPoint": {
            "coordinates": {
              "latitude": "29.76038",
              "longitude": "95.36981"
            },
            "source": "CALCULATED"
          }
        }
      },
      {
        "field": "$.locationDetails.mainAddress",
        "value": {
          "mainAddress": {
            "fullAddress": "5505 W Parmer Ln, Austin, TX 78727, United States",
            "locale": "en"
          }
        }
      }
    ],
    "compared": [],
    "expected": []
  }
}

Flow Chart

Following chart describes the system's behavior as it relates to this validation:

MustHaveMainAddressOrDisplayPoint

Definition	Severity	API	Sample	Mode
Validate that displayPoint or mainAddress is present. (May possess both)

Main Address

DistanceBetweenFullAndStructuredAddressGeocodesExceedsThreshold

Preconditions
fullAddress and structuredAddress are present and both are successfully geocoded

Definition	Severity	API	Sample	Mode
Validate that the distance between fullAddress and structuredAddress geocodes does not exceed a maximum distance (500 meters)

Example Validation Report

{
  "code": "VALIDATION__DistanceBetweenFullAndStructuredAddressGeocodesExceedsThreshold",
  "severity": "WARNING",
  "message": "Distance between full and structured address geocodes exceeds threshold",
  "details": {
    "createdDate": "2026-06-10T11:36:02.00Z",
    "submitted": [
      {
        "field": "$.locationDetails.mainAddress",
        "value": {
          "mainAddress": {
            "fullAddress": "5505 W Parmer Ln, Austin, TX 78727, United States",
            "structuredAddress": {
              "fullThoroughfare": "4101 W Parmer Ln",
              "thoroughfare": "W Parmer Ln",
              "subThoroughfare": "4101",
              "locality": "Austin",
              "administrativeArea": "TX",
              "countryCode": "US",
              "postCode": "78727"
            },
            "locale": "en"
          }
        }
      }
    ],
    "compared": [],
    "expected": []
  }
}

MainAddressMustHaveFullOrStructuredAddress

Preconditions
mainAddress is present

Definition	Severity	API	Sample	Mode
Validate that fullAddress or structuredAddress is present

Example Validation Report

{
  "code": "VALIDATION__MainAddressMustHaveFullOrStructuredAddress",
  "severity": "VIOLATION",
  "message": "Location has neither `fullAddress` nor `structuredAddress`. Provide one or other (or both). Or remove `mainAddress` and provide `displayPoint`"
}

MainAddressNotPresent

Definition	Severity	API	Sample	Mode
Validate that mainAddress is present

Example Validation Report

{
  "code": "VALIDATION__MainAddressNotPresent",
  "severity": "INFO",
  "message": "Location has no `mainAddress`"
}

Full Address

CountryNotAllowedForOrgType

Preconditions
orgId resolves to organization that is location owner

Definition	Severity	API	Sample	Mode
Validate that country derived from fullAddress is not China

Example Validation Report

{
  "code": "VALIDATION__CountryNotAllowedForOrgType",
  "severity": "VIOLATION",
  "message": "Country support for your organization type is not available"
}

CountryNotSupported

Definition	Severity	API	Sample	Mode
Validate that the country derived from a fullAddress is supported			Link

Example Validation Report

{
  "code": "VALIDATION__CountryNotSupported",
  "severity": "VIOLATION",
  "message": "Country support for 'fullAddress' not available"
}

DerivedCountryCodeMustMatchBrandCountryCodes

Preconditions
brandId is present
Either structuredAddress, fullAddress, or displayPoint (or both) is present. (Deference is given to structuredAddress, then fullAddress, followed by displayPoint)

Definition	Severity	API	Sample	Mode
Validate that the country derived from a structuredAddress, fullAddress, or displayPoint matches a listed country in the referenced brand

Example Validation Report

{
  "code": "VALIDATION__DerivedCountryCodeMustMatchBrandCountryCodes",
  "severity": "VIOLATION",
  "message": "Country code derived from `structuredAddress`, `fullAddress`, or `displayPoint` must match a referenced brand's country code"
}

Flow Chart

Following chart describes the system's behavior as it relates to this validation:

DisplayNamesNameIncludedInFullAddress

Definition	Severity	API	Sample	Mode
Validate that fullAddress does not include any Display Names

FullAddressIncludesPOBoxAddress

Definition	Severity	API	Sample	Mode
Validate that fullAddress does not include a PO Box address component

FullAddressLengthMustNotExceedMaximum

Definition	Severity	API	Sample	Mode
Validate that fullAddress length does not exceed a maximum value (300)			Link

FullAddressMustNotBeDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that fullAddress is not exclusively dummy characters			Link

FullAddressMustNotBeEntirelyNumeric

Definition	Severity	API	Sample	Mode
Validate that the fullAddress value is not entirely numeric

FullAddressMustNotIncludeURL

Definition	Severity	API	Sample	Mode
Validate that fullAddress does not include a URL

FullAddressMustNotIncludeVulgarWord

Definition	Severity	API	Sample	Mode
Validate that fullAddress does not include a vulgar word

FullAddressMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that fullAddress is not an empty string

MainAddressFullAddressHasUnsupportedCharacter

Definition	Severity	API	Sample	Mode
Validate that fullAddress does not include an unsupported character			Link

Structured Address

DisplayNamesNameIncludedInStructuredAddress

Definition	Severity	API	Sample	Mode
Validate that structuredAddress component does not include any Display Names

StructuredAddressComponentHasUnsupportedCharacter

Definition	Severity	API	Sample	Mode
Validate that an unsupported character is not included in any structuredAddress component

StructuredAddressMustIncludeComponent

Definition	Severity	API	Sample	Mode
Validate that a structuredAddress component is present when required for the country			Link

Example Validation Report

{
  "code": "VALIDATION__StructuredAddressMustIncludeComponent",
  "severity": "VIOLATION",
  "message": "'{{field}}' must be present",
  "context": {
    "field": "fullThoroughfare"
  }
}

Administrative Area

AdministrativeAreaIncludesVulgarWord

Definition	Severity	API	Sample	Mode
Validate that administrativeArea does not include a vulgar word

AdministrativeAreaMustNotExceedMaximum

Definition	Severity	API	Sample	Mode
Validate that administrativeArea length does not exceed a maximum value (255)

AdministrativeAreaMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that administrativeArea is not an empty string

Building

BuildingMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that building is not an empty string

BuildingMustNotExceedMaximum

Definition	Severity	API	Sample	Mode
Validate that building length does not exceed a maximum value (255)

BuildingMustNotIncludeURL

Definition	Severity	API	Sample	Mode
Validate that building does not include a URL

BuildingHasSuspectedUnintentionalSequentialWordRepetition

Definition	Severity	API	Sample	Mode
Validate that building does not include an unintentional repetitive sequence of words

BuildingMustNotBeDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that building is not exclusively dummy characters			Link

BuildingMustNotIncludeVulgarWord

Definition	Severity	API	Sample	Mode
Validate that building does not include a vulgar word

BuildingHasSuspectedPresenceOfDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that building does not include dummy characters

Country Code

CountryCodeMustBePresent

Preconditions
structuredAddress is present

Definition	Severity	API	Sample	Mode
Validate that countryCode is present			Link

CountryCodeMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that countryCode is not an empty string

CountryCodeMustBeValid

Definition	Severity	API	Sample	Mode
Validate that countryCode value is valid

CountryCodeNotSupported

Definition	Severity	API	Sample	Mode
Validate that a country code identifies a supported country			Link

Example Validation Report

{
  "code": "VALIDATION__CountryCodeNotSupported",
  "severity": "VIOLATION",
  "message": "Country support for '{{field}}' value '{{value}}' not available",
  "context": {
    "field": "countryCode",
    "value": "BY"
  },
  "details": {
    "createdDate": "2026-09-01T21:00:59.865Z",
    "submitted": [
      {
        "field": "$.locationDetails.mainAddress.structuredAddress.countryCode",
        "value": "BY"
      }
    ],
    "compared": [],
    "expected": []
  }
}

CountryCodeNotAllowedForOrgType

Preconditions
orgId resolves to organization that is location owner

Definition	Severity	API	Sample	Mode
Validate that countryCode is not "CN" (China)

Example Validation Report

{
  "code": "VALIDATION__CountryCodeNotAllowedForOrgType",
  "severity": "VIOLATION",
  "message": "Country support for your organization type is not available"
}

Dependent Locality

DependentLocalityIncludesNumericalCharacters

Definition	Severity	API	Sample	Mode
Validate that dependentLocality does not include numerical characters

DependentLocalityIncludesVulgarWord

Definition	Severity	API	Sample	Mode
Validate that dependentLocality does not include a vulgar word

DependentLocalityIsEntirelyNumerical

Definition	Severity	API	Sample	Mode
Validate that dependentLocality is not entirely numerical characters

DependentLocalityMustNotBeDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that dependentLocality is not exclusively dummy characters			Link

DependentLocalityMustNotBeEmptyArray

Definition	Severity	API	Sample	Mode
Validate that structuredAddress.dependentLocality is not an empty array

Example Validation Report

{
  "code": "VALIDATION__DependentLocalityMustNotBeEmptyArray",
  "message": "'{{field}}' must be omitted or contain at least one element; empty arrays are not allowed.",
  "severity": "VIOLATION",
  "context": {
    "field": "dependentLocality"
  },
  "details": {
    "compared": [],
    "expected": [],
    "submitted": [
      {
        "field": "$.locationDetails.structuredAddress.dependentLocality",
        "value": "[]"
      }
    ],
    "createdDate": "2026-03-03T13:58:43.946Z"
  }
}

DependentLocalityHasSuspectedPresenceOfDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that dependentLocality does not include dummy characters

DependentLocalityMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that dependentLocality is not an empty string

DependentLocalityMustNotExceedMaximum

Definition	Severity	API	Sample	Mode
Validate that dependentLocality length does not exceed a maximum value (50)

DependentLocalityMustNotIncludeNumericalCharacters

Definition	Severity	API	Sample	Mode
Validate that dependentLocality does not include numerical characters

MainAddressDependentLocalityMustNotIncludeURL

Definition	Severity	API	Sample	Mode
Validate that dependentLocality does not include a URL

Floor

FloorMustNotBeDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that floor is not exclusively dummy characters			Link

FloorHasSuspectedPresenceOfDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that floor does not include dummy characters

FloorMustNotIncludeVulgarWord

Definition	Severity	API	Sample	Mode
Validate that floor does not include a vulgar word

FloorMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that floor is not an empty string

FloorMustNotExceedMaximum

Definition	Severity	API	Sample	Mode
Validate that floor length does not exceed a maximum value (255)

FloorMustNotIncludeURL

Definition	Severity	API	Sample	Mode
Validate that floor does not include a URL

FloorHasSuspectedUnintentionalSequentialWordRepetition

Definition	Severity	API	Sample	Mode
Validate that floor does not include an unintentional repetitive sequence of words

Full Thoroughfare

FullThoroughfareIncludesVulgarWord

Definition	Severity	API	Sample	Mode
Validate that fullThoroughfare does not include a vulgar word

FullThoroughfareMustNotBeDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that fullThoroughfare is not exclusively dummy characters			Link

FullThoroughfareHasSuspectedPresenceOfDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that fullThoroughfare does not include dummy characters

FullThoroughfareMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that fullThoroughfare is not an empty string

FullThoroughfareMustNotExceedMaximum

Definition	Severity	API	Sample	Mode
Validate that fullThoroughfare length does not exceed a maximum value (255)

FullThoroughfareMustExceedMinimum

Definition	Severity	API	Sample	Mode
Validate that fullThoroughfare length exceeds a minimum value (2)

FullThoroughfareMustNotBeEntirelyNumeric

Definition	Severity	API	Sample	Mode
Validate that fullThoroughfare does not include numerical characters

FullThoroughfareMustNotIncludeURL

Definition	Severity	API	Sample	Mode
Validate that fullThoroughfare does not include a URL

Geocoding

AddressMustBeGeocoded

Preconditions
displayPoint is not present

Definition	Severity	API	Sample	Mode
Validate that mainAddress (fullAddress or structuredAddress) can be geocoded

FullAndStructuredAddressGeocodesNotEqual

Definition	Severity	API	Sample	Mode
Validate that fullAddress and structuredAddress geocodes (calculated coordinates) are equal

FullAndStructuredAddressGeocodesNotInProximity

Definition	Severity	API	Sample	Mode
Validate that fullAddress and structuredAddress geocodes (calculated coordinates) are within proximity of one another (1 meter distance)

FullAddressGeocodingUnsuccessful

Definition	Severity	API	Sample	Mode
Validate that fullAddress can be geocoded

StructuredAddressGeocodingUnsuccessful

Definition	Severity	API	Sample	Mode
Validate that structuredAddress can be geocoded

Locality

LocalityIncludesVulgarWord

Definition	Severity	API	Sample	Mode
Validate that locality does not include a vulgar word

LocalityIsEntirelyNumericalCharacters

Definition	Severity	API	Sample	Mode
Validate that locality is not entirely numerical characters

LocalityMustNotBeDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that locality is not exclusively dummy characters			Link

LocalityHasSuspectedPresenceOfDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that locality does not include dummy characters

LocalityMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that locality is not an empty string

LocalityMustNotExceedMaximum

Definition	Severity	API	Sample	Mode
Validate that locality length does not exceed a maximum value (255)			Link

LocalityMustNotIncludeNumericalCharacters

Definition	Severity	API	Sample	Mode
Validate that locality does not include numerical characters

LocalityMustNotIncludeURL

Definition	Severity	API	Sample	Mode
Validate that locality does not include a URL

Post Code

PostCodeIncludesVulgarWord

Definition	Severity	API	Sample	Mode
Validate that postCode does not include a vulgar word

PostcodeMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that postCode is not an empty string

PostCodeFormatMustBeValidForCountryCode

Preconditions
structuredAddress is present

Definition	Severity	API	Sample	Mode
Validate that postCode format is valid for corresponding country identified by countryCode in structuredAddress

PostCodeMustNotBeDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that postCode is not exclusively dummy characters			Link

PostCodeMustNotExceedMaximum

Definition	Severity	API	Sample	Mode
Validate that postCode length does not exceed a maximum value (10)

Sub-Administrative Area

SubAdministrativeAreaIncludesNumericalCharacters

Definition	Severity	API	Sample	Mode
Validate that subAdministrativeArea does not include numerical characters

SubAdministrativeAreaIncludesVulgarWord

Definition	Severity	API	Sample	Mode
Validate that subAdministrativeArea does not include a vulgar word

SubAdministrativeAreaIsEntirelyNumericalCharacters

Definition	Severity	API	Sample	Mode
Validate that subAdministrativeArea is not entirely numerical characters

SubAdministrativeAreaMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that subAdministrativeArea is not an empty string

SubAdministrativeAreaMustNotIncludeURL

Definition	Severity	API	Sample	Mode
Validate that subAdministrativeArea does not include a URL

SubAdministrativeAreaMustNotExceedMaximum

Definition	Severity	API	Sample	Mode
Validate that subAdministrativeArea length does not exceed a maximum value (255)			Link

SubAdministrativeAreaMustNotIncludeNumericalCharacters

Definition	Severity	API	Sample	Mode
Validate that subAdministrativeArea does not include numerical characters

SubAdministrativeAreaMustNotBeDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that subAdministrativeArea is not exclusively dummy characters			Link

SubAdministrativeAreaHasSuspectedPresenceOfDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that subAdministrativeArea does not include dummy characters

Sub-Locality

SubLocalityIncludesNumericalCharacters

Definition	Severity	API	Sample	Mode
Validate that sublocality does not include numerical characters

SubLocalityIsEntirelyNumericalCharacters

Definition	Severity	API	Sample	Mode
Validate that sublocality is not entirely numerical characters

SubLocalityMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that subLocality is not an empty string

SubLocalityMustNotIncludeURL

Definition	Severity	API	Sample	Mode
Validate that subLocality does not include a URL

SubLocalityMustNotExceedMaximum

Definition	Severity	API	Sample	Mode
Validate that subLocality length does not exceed a maximum value (255)

SubLocalityMustNotIncludeNumericalCharacters

Definition	Severity	API	Sample	Mode
Validate that subLocality does not include numerical characters

SubLocalityMustNotBeDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that subLocality is not exclusively dummy characters			Link

SubLocalityHasSuspectedPresenceOfDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that subLocality does not include dummy characters

Sub-thoroughfare

SubThoroughfareIncludesVulgarWord

Definition	Severity	API	Sample	Mode
Validate that subThoroughfare does not include a vulgar word

SubThoroughfareMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that subThoroughfare is not an empty string

SubThoroughfareMustNotExceedMaximum

Definition	Severity	API	Sample	Mode
Validate that subThoroughfare length does not exceed a maximum value (255)			Link

SubThoroughfareMustNotBeDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that subThoroughfare is not exclusively dummy characters			Link

SubThoroughfareHasSuspectedPresenceOfDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that subThoroughfare does not include dummy characters

SubThoroughfarePresentWithoutThoroughfare

Definition	Severity	API	Sample	Mode
Validate that subThoroughfare is not present when thoroughfare is also not present			Link

Example Validation Report

{
  "code": "VALIDATION__SubThoroughfarePresentWithoutThoroughfare",
  "severity": "WARNING",
  "message": "'{{field}}' has value '{{value}}'. `thoroughfare` typically accompanies '{{field}}'",
  "context": {
    "field": "subThoroughfare",
    "value": "23"
  }
}

Thoroughfare

ThoroughfareIncludesVulgarWord

Definition	Severity	API	Sample	Mode
Validate that thoroughfare does not include a vulgar word

StructuredAddressMustIncludeFullThoroughfareOrThoroughfare

Preconditions
structuredAddress is present

Definition	Severity	API	Sample	Mode
Validate that fullThoroughfare or thoroughfare is present when conditionally required			Link

ThoroughfareMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that thoroughfare is not an empty string

ThoroughfareMustNotExceedMaximum

Definition	Severity	API	Sample	Mode
Validate that thoroughfare length does not exceed a maximum value (255)			Link

ThoroughfareMustNotBeDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that thoroughfare is not exclusively dummy characters			Link

ThoroughfareHasSuspectedPresenceOfDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that thoroughfare does not include dummy characters

Unit

UnitMustNotBeDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that unit is not exclusively dummy characters			Link

UnitMustNotIncludeURL

Definition	Severity	API	Sample	Mode
Validate that unit does not include a URL			Link

Example Validation Report

{
  "code": "VALIDATION__UnitMustNotIncludeURL",
  "severity": "VIOLATION",
  "message": "'{{field}}' is '{{value}}' and includes URL",
  "context": {
    "field": "unit",
    "value": "http://www.example.com/"
  },
  "details": {
    "createdDate": "2026-08-10T11:36:02.00Z",
    "submitted": [
      {
        "field": "$.locationDetails.mainAddress.structuredAddress.unit",
        "value": "http://www.example.com/"
      }
    ],
    "compared": [],
    "expected": []
  }
}

UnitMustNotIncludeVulgarWord

Definition	Severity	API	Sample	Mode
Validate that unit does not include a vulgar word

UnitHasSuspectedPresenceOfDummyCharacters

Definition	Severity	API	Sample	Mode
Validate that unit does not include dummy characters

UnitMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that unit is not an empty string

UnitMustNotExceedMaximum

Definition	Severity	API	Sample	Mode
Validate that unit length does not exceed a maximum value (255)			Link

UnitHasSuspectedUnintentionalSequentialWordRepetition

Definition	Severity	API	Sample	Mode
Validate that unit does not include an unintentional repetitive sequence of words

Locale

MainAddressRequiresAtLeastOneSupportedLocale

Definition	Severity	API	Sample	Mode
Validate that at least one (1) supported locale is present

MainAddressLocaleMustBePresent

Preconditions
mainAddress is present

Definition	Severity	API	Sample	Mode
Validate that locale is present			Link

MainAddressLocaleMustBeValid

Definition	Severity	API	Sample	Mode
Validate that locale is valid			Link

MainAddressLocaleMustNotBeEmpty

Preconditions
mainAddress is present

Definition	Severity	API	Sample	Mode
Validate that locale is not an empty string