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 three 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")

Test data then uses the postal code 99501 (Anchorage, Alaska) instead of a random value. default also accepts a list of candidate postal codes, from which each simulated respondent picks one at random.

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. Defaults to "What is your zipcode?".
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. Defaults to "Which city best describes where you live?".
report (Sequence[str], optional) - The derived location fields to report. Defaults to ("region",). Must be a nonempty, non-string sequence (such as a list or tuple) of fields supported for the selected country; unsupported fields add survey validation errors. Pass a list to report multiple levels.
strict (bool, optional) - Whether to terminate the respondent when the postal-code capture or the validation question leaves an active validation warning. Default: False.
style (str, optional) - The primary input style, either text or autocomplete. Defaults to text.
country (str | 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 | list[str], optional) - The postal code to use when generating test data, or a list of candidate postal codes from which each simulated respondent picks one at random. 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 applied to the derived report fields: a single report field uses id directly, while multiple fields use {id}-{field}. If not set, each derived field uses its generated question identity. See Stable question identifiers.

Reporting Behavior

The survey records the respondent's location at each level listed in report. The question returns the entered postal code as a StringResponse; the derived report fields are added for reporting but are not part of the return value. The returned object also exposes all other location fields for that postal code. For example:

loc = s.location_question(report=["region"])
cbsa = 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.