Location Question

The Location Question collects a respondent's location from their postal code (zipcode) and derives reportable geographic fields from it. It is added with s.location_question(...) and works in two steps:

The respondent is asked to enter the location field set by field (a postal code by default).
The system validates the entry by asking a separate follow-up question about where they live, set by validation_field. The respondent is shown a number of options (configurable with number_options) and must select the correct one. Set validation_field=None to skip validation.
The location is reported at the levels you list in report.

Example Usage

location = s.location_question(report=["region", "state", "market"])

This asks the respondent for their postal code, validates it with the default city follow-up, and reports their location at the region, state, and market levels. Because report accepts a list, a single question can contribute several geographic levels to your data.

To set a test-data default and target a specific country:

s.location_question(report=["region"], default="99501", country="US")

If no postal code is entered, the default 99501 (Anchorage, Alaska) is used in test data.

Default Behavior

If no default value is specified, test data uses random values from the location database.
The question adds both a postal code entry field and a validation step, unless validation is skipped with validation_field=None or the postal code is already known (e.g. provided by a sample provider).
country defaults to the respondent's country, or the US when that is unavailable.

The user experience uses the text question and select question.

Recodes

The location question does not support recodes.

Parameters

field (str, optional) - The location field to ask for first. Defaults to postal_code.
question (str, optional) - The primary location question copy.
validation_field (str | None, optional) - The location field to validate the entry against. Use None to skip validation. Defaults to city.
validation_question (str, optional) - The validation follow-up question copy.
report (Sequence[str], optional) - The derived location fields to report. Defaults to ("region",). Pass a list to report multiple levels.
strict (bool, optional) - Whether to terminate the respondent if they enter invalid location data. Default: False.
style (str, optional) - The primary input style. Only text is supported for now.
country (Mx8Country | None, optional) - Optional country override. Defaults to the respondent's country, or US.
tags (s.tag(), optional) - Used for token substitution in the question and grouping results in reporting.
default (str, optional) - The default postal code to use when generating test data. Set this for surveys with a limited geography. If omitted, test data uses random values from the location database.
number_options (int, optional) - The number of matching locations shown to the respondent during the validation step. Default: 5.
number_seconds (int, optional) - Seconds to wait before allowing the respondent to continue. Default: 0.
id (str, optional) - Stable identifier for this question; if not set, the question text is used. See Stable question identifiers.

Reporting Behavior

The survey records the respondent's location at each level listed in report. The returned object also exposes all other location fields for that postal code. For example:

loc = s.location_question(report=["region"])
if loc.cbsa == ...  # Access the CBSA name

If you need to include these additional fields in your survey data explicitly, you can store them with:

s.store_value("CBSA", loc.cbsa)

This lets you capture multiple geographic levels for analysis while reporting only the levels you choose.

Country-Specific Options

Use the lower-case value in validation_field and report to target each level below (e.g., state_code, cbsa).

United States

Level (human)	Use this code	What it returns	Example from dataset
City	`city`	City name resolved from the ZIP	Anchorage
County	`county`	County name	Anchorage Municipality
State	`state`	Full state name	Alaska
State Code	`state_code`	Two-letter USPS code	AK
Market	`market`	Market/DMA label when available, otherwise `UNKNOWN`	ANCHORAGE
CBSA	`cbsa`	Core-Based Statistical Area label (may be `UNKNOWN` for some ZIPs)	Anchorage, AK
Region	`region`	Broad US region	West

United Kingdom

Level (human)	Use this code	What it returns	Example from dataset
City	`city`	City/town resolved from the postcode	Birmingham
Region	`region`	Administrative area (e.g., county/metropolitan region)	West Midlands / Bedfordshire
Nation	`nation`	England, Scotland, Wales, or Northern Ireland	England

UK Example Datapoints

postal_code,city,nation,region AL53NG%,Harpenden,England,Bedfordshire B11%,Birmingham,England,West Midlands

Value Formats

The exact string returned for a level follows a fixed convention. When you filter, quota, or recode on these values, match the casing and spelling shown here.

For low-cardinality levels the full set of possible values is fixed, so you can safely match against the complete list below. For high-cardinality levels (city, county, market, CBSA, and UK region) the values follow the source data — match on the format and casing rather than maintaining an exhaustive list.

United States — fixed value sets:

region — exactly one of Northeast, Midwest, South, West (title case). May be blank for ZIPs not assigned to a census region (e.g. some territories).
state — full state name in title case (e.g. California, District of Columbia). The set also includes Marshall Islands. Unresolved ZIPs return UNKNOWN.
state_code — two-letter uppercase USPS code matching the state (e.g. CA, DC, MH). Unresolved ZIPs return UNKNOWN.

United States — high-cardinality (format only):

city — source city name in title case (e.g. Anchorage).
county — full county name including its type suffix where present (e.g. San Diego, Anchorage Municipality).
market — DMA label in UPPERCASE (e.g. SAN DIEGO, ORLANDO - DAYTONA BCH - MELBRN). May be UNKNOWN.
cbsa — Place, ST format (e.g. Orlando-Kissimmee-Sanford, FL). May be UNKNOWN.

United Kingdom — fixed value sets:

nation — exactly one of England, Scotland, Wales, Northern Ireland (title case). May be blank for some postcodes.

United Kingdom — high-cardinality (format only):

city — town/city name in title case (e.g. Birmingham, Harpenden).
region — administrative area name in title case (e.g. West Midlands, Bedfordshire, Argyll and Bute).

Notes

During validation, respondents are shown up to number_options place options at the chosen level and must select the correct one.
Use the lower-case codes shown above in both validation_field and report.
cbsa and market may return UNKNOWN for certain ZIP codes (typically in remote areas).
validation_field determines the level at which the respondent must confirm their location from the provided list of options.
report determines which geographic levels are included in reporting outputs.