Address masking policy (standard)

Edit online

The Address category provides standard masking policy formats for US street suffixes, street names, full street addresses, and ZIP codes. Use these formats to mask location data while preserving structural validity.

Parameters

The Address masking policy accepts the following parameters.

Table 1. Address masking policy parameters
Parameter	Required	Type	Description
`name`	Yes	String	The format name. Must be one of: `StreetSuffix`, `StreetSuffix_CaseSensitive`, `USAddressSimple`, `USAddressWithSecondary`, `USStreetNames_CaseSensitive`, `USZipCodes_CaseSensitive`.
`type`	Yes	String	The processor type. Accepted values depend on the format. See each format section for supported processors.
`config`	No	Object	Pass `{}` or omit entirely. No additional configuration keys are supported for any address format.

StreetSuffix format

Masks a US street suffix by replacing it with a different value from the USPS-standardized dictionary of street suffix abbreviations and full-word equivalents. The format is case-insensitive - BLVD, blvd, and Blvd all match the same entry. All outputs are returned in lowercase. All four processors are supported.

Valid input values

Example input	Why it is valid
`BLVD`	Standard BOULEVARD abbreviation
`AVE`	Standard avenue abbreviation
`AVE.`	Period-terminated variant. Distinct entry from `AVE`
`STRAVENUE`	Uncommon full-word form

Invalid input values

Value	Reason	`FormatPreservingRedactionProcessor`	`FormatPreservingTokenizationProcessor`	`RandomFormatFabricationProcessor` / `RepeatableFormatFabricationProcessor`
`BLVD..`	Double period. Not an entry	`IllegalArgumentException`	`MagenPayloadException`	Returns valid suffix
`NORTH`	Directional. Not a street suffix	`IllegalArgumentException`	`MagenPayloadException`	Returns valid suffix
`BLVD ST`	Two tokens. Not a single entry	`IllegalArgumentException`	`MagenPayloadException`	Returns valid suffix
(empty string)	Zero-length input	`IllegalArgumentException`	`MagenPayloadException`	Returns valid suffix

Processors

FormatPreservingRedactionProcessor

Replaces every valid input with allee - the zero-rank entry in the dictionary.

Use when: Deterministic suppression where no differentiation between source values is required.

Input	Output
`BLVD`	`allee`
`AVE`	`allee`

FormatPreservingTokenizationProcessor

Produces a deterministic token for every valid dictionary input. The same input always produces the same output for the same IV.

Use when: The same source suffix must consistently map to the same masked value - for example, a column used in a join or group-by.

Input	Output	Notes
`BLVD`	`ldge`	Case-insensitive - same as `blvd`
`AVE.`	`sts`	Distinct entry from `AVE`

RandomFormatFabricationProcessor

Generates a new random suffix on each invocation. Non-deterministic.

Use when: Masking a non-key suffix column where run-to-run consistency is not required.

RepeatableFormatFabricationProcessor

Produces a deterministic fabricated suffix. The same input always produces the same output for the same IV.

Use when: Masking a street suffix that is a primary key, foreign key, or join key where referential integrity must be maintained.

Configuration examples

FormatPreservingRedactionProcessor

{
  "column_name_source": "street_suffix",
  "column_name_target": "street_suffix_masked",
  "masking_properties": {
    "magen_function": {
      "name": "StreetSuffix",
      "type": "FormatPreservingRedactionProcessor",
      "config": {}
    }
  }
}

FormatPreservingTokenizationProcessor

{
  "column_name_source": "street_suffix",
  "column_name_target": "street_suffix_masked",
  "masking_properties": {
    "magen_function": {
      "name": "StreetSuffix",
      "type": "FormatPreservingTokenizationProcessor",
      "config": { "mode": "tokenize" }
    }
  }
}

Known limitations

Period-terminated variants are distinct entries: AVE and AVE. are separate dictionary entries with separate ranks and produce separate masked outputs. Normalize input before masking if consistency is required.
Output is always lowercase: All outputs are returned in lowercase regardless of input casing.
CHAR(n) column length: A masked suffix can be up to 10 characters (expressway, stravenue, trafficway). Use VARCHAR or set CHAR(n) to at least 10.
NULL handling: NULL values are passed through unchanged.

StreetSuffix_CaseSensitive format

Masks a US street suffix by replacing it with a different value from the USPS-standardized dictionary. Unlike StreetSuffix, this format is case-sensitive - only uppercase entries are in the dictionary, so lowercase or mixed-case inputs such as blvd or Blvd are treated as non-dictionary inputs. All outputs are returned in uppercase. Supports RandomFormatFabricationProcessor and RepeatableFormatFabricationProcessor only.

Dictionary inputs (uppercase only)

Example input	Note
`BLVD`	Present in dictionary - standard BOULEVARD abbreviation
`AVE`	Present in dictionary - standard avenue abbreviation
`STRAVENUE`	Present in dictionary - uncommon full-word form

Non-dictionary inputs

Example input	Reason	Engine behavior
`blvd`	Lowercase - dictionary contains only uppercase	Returns random or deterministic valid uppercase suffix
`Blvd`	Mixed case - dictionary contains only uppercase	Returns random or deterministic valid uppercase suffix
`NORTH`	Directional - not a street suffix	Returns random or deterministic valid uppercase suffix

Processors

RandomFormatFabricationProcessor

Generates a new fabricated uppercase suffix on every invocation. Non-deterministic.

Use when: Masking a non-key suffix column where run-to-run consistency is not required.

RepeatableFormatFabricationProcessor

Produces a deterministic fabricated uppercase suffix. The same input produces the same output for the same IV. Non-dictionary inputs take the hash path. They produce different output from BLVD even for the same IV.

Use when: Masking a street suffix that is a primary key, foreign key, or join key.

Input	Output (run 1)	Output (run 2)	Notes
`BLVD`	`LDGE`	`LDGE` (same)	Dictionary lookup path
`blvd`	`FORK`	`FORK` (same)	Hash path - different output from `BLVD`

Configuration examples

RandomFormatFabricationProcessor

{
  "column_name_source": "street_suffix",
  "column_name_target": "street_suffix_masked",
  "masking_properties": {
    "magen_function": {
      "name": "StreetSuffix_CaseSensitive",
      "type": "RandomFormatFabricationProcessor",
      "config": {}
    }
  }
}

RepeatableFormatFabricationProcessor

{
  "column_name_source": "street_suffix",
  "column_name_target": "street_suffix_masked",
  "masking_properties": {
    "magen_function": {
      "name": "StreetSuffix_CaseSensitive",
      "type": "RepeatableFormatFabricationProcessor",
      "config": {}
    }
  }
}

Known limitations

Uppercase only: Only uppercase inputs match the dictionary. Lowercase or mixed-case inputs take the hash path under RepeatableFormatFabricationProcessor or produce a random output under RandomFormatFabricationProcessor.
No redaction or tokenization support: FormatPreservingRedactionProcessor and FormatPreservingTokenizationProcessor are not supported.
NULL handling: NULL values are passed through unchanged.

USAddressSimple format

Masks a simple US street address by replacing the house number, street name, and street type with fabricated equivalents while preserving the overall address structure. The output is always a valid address in the form <HouseNumber> <StreetName> <StreetType>. Supports RandomFormatFabricationProcessor and RepeatableFormatFabricationProcessor only.

The format recognizes exactly 24 street type tokens - 12 full-word forms and 12 abbreviations, all title-cased: Avenue / Ave, Boulevard / Blvd, Circle / Cir, Court / Ct, Expressway / Expy, Freeway / Fwy, Lane / Ln, Parkway / Pky, Road / Rd, Square / Sq, Street / St, Turnpike / Tpke. The maximum output length is 38 characters (99999 Yeldall Manor Service Expressway).

Valid input values

Value	Structure
`58664 Db Fwy`	House number `58664`, street name `Db`, type `Fwy`
`4634 Gateway Center Boulevard`	House number `4634`, multi-word street name, type `Boulevard`
`9 Oak Ave`	1-digit house number, single-word name, abbreviated type

Invalid input values

Value	Reason	Engine behavior
`58664 Db FREEWAY`	Street type `FREEWAY` is all-caps. Only title-cased tokens are recognized	Returns random or deterministic valid address
`1234 Main Dr`	`Dr` is not one of the 12 recognized street types	Returns random or deterministic valid address
`Main Street`	No house number present	Returns random or deterministic valid address
`0 Oak Street`	House number `0` is outside the 1-99999 range	Returns random or deterministic valid address

Processors

RandomFormatFabricationProcessor

Generates a new valid address on every invocation. Non-deterministic.

Use when: Masking an address column where referential consistency is not required.

RepeatableFormatFabricationProcessor

Produces a deterministic fabricated address. The same input always produces the same output for the same IV.

Use when: Masking an address column that is referenced as a primary key, foreign key, or join key.

Configuration examples

RandomFormatFabricationProcessor

{
  "column_name_source": "street_address",
  "column_name_target": "street_address",
  "masking_properties": {
    "magen_function": {
      "name": "USAddressSimple",
      "type": "RandomFormatFabricationProcessor",
      "config": {}
    }
  }
}

RepeatableFormatFabricationProcessor

{
  "column_name_source": "street_address",
  "column_name_target": "street_address",
  "masking_properties": {
    "magen_function": {
      "name": "USAddressSimple",
      "type": "RepeatableFormatFabricationProcessor",
      "config": {}
    }
  }
}

Known limitations

Only 12 street types are recognized: Common types such as Drive, Place, Trail, and Way are not part of this format's vocabulary. Addresses with any other street type are masked via the hash path.
Case sensitivity - only title-cased street types are recognized: Avenue, Blvd, and Fwy are recognized; AVENUE, blvd, and ave. are not. Normalize input to title case before applying this policy.
CHAR(n) column length: A fabricated address can be up to 38 characters. Use VARCHAR or ensure CHAR(n) is sufficient.
No redaction or tokenization support: FormatPreservingRedactionProcessor and FormatPreservingTokenizationProcessor are not supported.
NULL handling: NULL values are passed through unchanged.

USAddressWithSecondary format

Masks a US street address that includes a secondary unit designator and unit number. All variable parts - house number, street name, street type, and unit number - are replaced with fabricated equivalents while the separator and overall address structure are preserved. The output is always a valid address in the form <HouseNumber> <StreetName> <StreetType><sep><UnitDesignator> <UnitNumber>. The maximum output length is 55 characters. Supports RandomFormatFabricationProcessor and RepeatableFormatFabricationProcessor only.

The format recognizes 13 unit designator tokens - 6 abbreviated and 7 full-word, all title-cased: Apt / Apartment, Bldg / Building, Fl / Floor, Ste / Suite, Rm / Room, Dept / Department, Unit.

The separator between the street type and the unit designator (, or ) is preserved verbatim.

Valid input values

Example input	Why it is valid
`13247 Brehme Expressway Floor 8641`	Space separators; full-word designator `Floor`; 4-digit unit number
`7821 Riverside Ave, Apt 12`	Comma+space separator; abbreviated designator `Apt`; 2-digit unit number

Invalid input values

Example input	Reason	Engine behavior
`13247 Brehme EXPRESSWAY Floor 8641`	Street type `EXPRESSWAY` is all-caps	Returns random or deterministic valid address
`48033 Happyland Boulevard`	No secondary unit present	Returns random or deterministic valid address

Processors

RandomFormatFabricationProcessor

Generates a new valid address with secondary unit on every invocation. Both separators are preserved from the input.

Use when: Masking a non-key address-with-unit column where run-to-run consistency is not required.

RepeatableFormatFabricationProcessor

Produces a deterministic fabricated address with secondary unit. The separator from the input is preserved in the output.

Use when: Masking an address-with-unit column that is referenced as a primary key, foreign key, or join key.

Configuration examples

RandomFormatFabricationProcessor

{
  "column_name_source": "full_address",
  "column_name_target": "full_address",
  "masking_properties": {
    "magen_function": {
      "name": "USAddressWithSecondary",
      "type": "RandomFormatFabricationProcessor",
      "config": {}
    }
  }
}

RepeatableFormatFabricationProcessor

{
  "column_name_source": "full_address",
  "column_name_target": "full_address",
  "masking_properties": {
    "magen_function": {
      "name": "USAddressWithSecondary",
      "type": "RepeatableFormatFabricationProcessor",
      "config": {}
    }
  }
}

Known limitations

USAddressWithSecondary does not match plain USAddressSimple inputs: An address without a secondary unit (for example, 1234 Oak Street) does not conform to the USAddressWithSecondary format and is treated as non-matching. Use USAddressSimple for addresses without a unit designator.
NULL handling: NULL values are passed through unchanged.

USStreetNames_CaseSensitive format

Masks a US street name word or phrase by replacing it with a different value drawn from a dictionary of 91,660 real US street name words and phrases. The format is case-sensitive - dictionary entries are stored in title case, so aaron and MAPLE are treated as non-dictionary inputs. The maximum output length is 21 characters. Supports RandomFormatFabricationProcessor and RepeatableFormatFabricationProcessor only.

Dictionary inputs

Example input	Note
`Aaron`	Single word - present in the dictionary
`Aaron Hill`	Multi-word phrase - present in the dictionary
`A.J. Hare`	Abbreviation-in-name - present in the dictionary

Non-dictionary inputs

Example input	Why it is not in the dictionary
`aaron`	All-lowercase - dictionary stores title-case entries
`Oak Street`	Contains a suffix word - street name entries do not include suffix tokens
`123 Main`	Contains a digit - no entries contain digits

Processors

RandomFormatFabricationProcessor

Generates a new fabricated street name entry on every invocation. Non-deterministic.

Use when: Masking a street name column where referential consistency is not required.

RepeatableFormatFabricationProcessor

Produces a deterministic fabricated street name. The same input always produces the same output for the same IV. Note that aaron and Aaron take different paths and produce different outputs even for the same IV.

Use when: Masking a street name that is a primary key, foreign key, or join key.

Configuration examples

RepeatableFormatFabricationProcessor

{
  "column_name_source": "street_name",
  "column_name_target": "street_name_masked",
  "masking_properties": {
    "magen_function": {
      "name": "USStreetNames_CaseSensitive",
      "type": "RepeatableFormatFabricationProcessor",
      "config": {}
    }
  }
}

Known limitations

Case sensitivity affects the masked value and masking path: Aaron, aaron, and AARON are treated as three distinct inputs. Only Aaron takes the dictionary lookup path. Normalize input casing before applying this policy.
Multi-word outputs may not fit narrow CHAR(n) columns: Masked output can be up to 21 characters. Use VARCHAR.
No redaction or tokenization support: FormatPreservingRedactionProcessor and FormatPreservingTokenizationProcessor are not supported.
NULL handling: NULL values are passed through unchanged.

USZipCodes_CaseSensitive format

Masks a US 5-digit ZIP code by replacing it with a different value drawn from a dictionary of 43,582 real US ZIP codes. The output is always a valid 5-digit ZIP code from the dictionary, zero-padded (for example, 00210). All four processors are supported.

Valid input values

Example input	Note
`00210`	Lowest ZIP code - rank 0
`10001`	New York, NY
`90210`	Beverly Hills, CA
`99950`	Highest ZIP code - last rank

Invalid input values

Value	Reason	`FormatPreservingRedactionProcessor`	`FormatPreservingTokenizationProcessor`	`RandomFormatFabricationProcessor` / `RepeatableFormatFabricationProcessor`
`10001-1234`	ZIP+4 - not a 5-digit entry	`IllegalArgumentException`	`MagenPayloadException`	Returns valid ZIP
`1000`	4 digits - too short	`IllegalArgumentException`	`MagenPayloadException`	Returns valid ZIP
`00000`	Not an active ZIP code - not in dictionary	`IllegalArgumentException`	`MagenPayloadException`	Returns valid ZIP

Processors

FormatPreservingRedactionProcessor

Replaces every valid input with 00210 - the zero-rank entry in the dictionary.

Use when: Deterministic suppression of ZIP code information where no differentiation between source values is required.

FormatPreservingTokenizationProcessor

Produces a deterministic token for every valid dictionary input. The same input always produces the same output for the same IV. Supports tokenize and detokenize modes.

Use when: Masking a ZIP code column where the same source value must consistently map to the same masked value - for example, a column used in a join, group-by, or geographic aggregation.

RandomFormatFabricationProcessor

Generates a new fabricated ZIP code on every invocation. Non-deterministic.

Use when: Masking a non-key ZIP code column where referential consistency is not required.

RepeatableFormatFabricationProcessor

Produces a deterministic fabricated ZIP code. The same input always produces the same output for the same IV.

Use when: Masking a ZIP code column that is referenced as a primary key, foreign key, or join key.

Configuration examples

FormatPreservingRedactionProcessor

{
  "column_name_source": "zip_code",
  "column_name_target": "zip_code_masked",
  "masking_properties": {
    "magen_function": {
      "name": "USZipCodes_CaseSensitive",
      "type": "FormatPreservingRedactionProcessor",
      "config": {}
    }
  }
}

FormatPreservingTokenizationProcessor

{
  "column_name_source": "zip_code",
  "column_name_target": "zip_code_masked",
  "masking_properties": {
    "magen_function": {
      "name": "USZipCodes_CaseSensitive",
      "type": "FormatPreservingTokenizationProcessor",
      "config": { "mode": "tokenize" }
    }
  }
}

RepeatableFormatFabricationProcessor

{
  "column_name_source": "zip_code",
  "column_name_target": "zip_code_masked",
  "masking_properties": {
    "magen_function": {
      "name": "USZipCodes_CaseSensitive",
      "type": "RepeatableFormatFabricationProcessor",
      "config": {}
    }
  }
}

Known limitations

ZIP+4 extended codes not supported: Codes in the format 10001-1234 are not valid inputs. Redaction and tokenization processors throw an error; fabrication processors silently return a valid 5-digit ZIP code.
NULL handling: NULL values are passed through unchanged.