address.state

Generates realistic US state and Canadian province/territory names for address generation. Supports both full names and standard 2-letter postal abbreviations for all 50 US states plus District of Columbia, and all 10 Canadian provinces plus 3 territories.

Keywords

countryoptional

Specifies which country's states/provinces to generate. Must be one of: US (default) or CA. When not specified, generates US states.

styleoptional

Specifies the output format. Must be one of: short (default) or full. Short generates 2-letter postal abbreviations, while full generates complete state/province names.

Behavior

The generated state/province names follow official postal standards:

• US (default country, short style): 2-letter state abbreviations (e.g., CA, NY, TX)
  • Includes all 50 US states
  • Includes District of Columbia (DC)
  • Uses official USPS abbreviations
• US (full style): Complete state names (e.g., California, New York, Texas)
• CA (Canadian, short style): 2-letter province/territory abbreviations (e.g., ON, BC, QC)
  • Includes all 10 provinces
  • Includes all 3 territories
  • Uses official Canada Post abbreviations
• CA (Canadian, full style): Complete province/territory names (e.g., Ontario, British Columbia, Quebec)

Additional characteristics:

• Values are not guaranteed to be unique
• Generation is deterministic based on the simulation seed
• All states/provinces have equal probability of selection
• Invalid country or style values will return an error

Examples

Default US state (short style):

{
  "type": "address.state"
}

Example outputs:

• CA
• NY
• TX
• FL

US states (full names):

{
  "type": "address.state",
  "country": "US",
  "style": "full"
}

Example outputs:

• California
• New York
• Texas
• Florida

Canadian provinces (short style):

{
  "type": "address.state",
  "country": "CA",
  "style": "short"
}

Example outputs:

• ON
• BC
• QC
• AB

Canadian provinces (full names):

{
  "type": "address.state",
  "country": "CA",
  "style": "full"
}

Example outputs:

• Ontario
• British Columbia
• Quebec
• Alberta

In an entity definition:

{
  "entities": {
    "customer": {
      "fields": {
        "name": {
          "type": "person.name"
        },
        "streetAddress": {
          "type": "address.address1"
        },
        "city": {
          "type": "string",
          "minLength": 3,
          "maxLength": 20
        },
        "state": {
          "type": "address.state",
          "country": "US",
          "style": "short"
        },
        "postalCode": {
          "type": "address.postalCode",
          "country": "US"
        }
      }
    }
  }
}

Notes

This schema generates state/province names suitable for testing and simulation purposes. All states and provinces are selected randomly with equal probability.

For complete mailing addresses, combine this schema with other address components like address.address1, address.address2, city, and address.postalCode.

When using region-specific states/provinces, ensure your simulation also uses appropriate values for related fields. For example, Canadian provinces should be paired with Canadian postal codes (country: "CA" in address.postalCode).

The short style (2-letter abbreviations) is recommended for most use cases as it follows standard postal conventions and is more compact. Use the full style when you need human-readable state/province names for display purposes.