The Location Question allows you to collect a respondent’s location based on their postal code (zipcode). It works in two steps:

1. The respondent is asked to enter their postal code.
2. The system validates the postal code by asking a separate follow-up question about where they live. The respondent is shown a number of options (configurable by number_options) and must select the correct one. This ensures both accuracy and respondent confirmation.
3. The location is reported based on the level you specify with reporting_type.

Example Usage

s.get_location(validation_type="state", reporting_type="region", default="99501")

This example asks the respondent for their postal code, validates it against state-level data, and reports their location at the ** region** level. If no postal code is entered, the default value 99501 (Anchorage, Alaska) will be used in test data.

Default Behavior

• If no default value is specified, test data will use random values from the location database.
• The question adds both a **postal code entry field ** and a validation step, unless the postal code is already known (e.g. provided by a sample provider).
• The location is always reported at the level you specify with reporting_type.

The user experience uses the text question and select question.

Recodes

The location question does not support recodes.

Parameters

• validation_type (str, optional) – The geographic level used to validate the respondent’s postal code.
• reporting_type (str, optional) – The geographic level used to report the respondent’s location in survey outputs.
• default (str, optional) – The default postal code to use when generating test data. Set this for surveys with a limited geography
• number_options (int, optional) – The number of suggested options shown to the respondent during the validation step. Default: 5.

Reporting Behavior

When you call get_location, the survey will record the respondent’s location at the level specified by reporting_type. However, the returned object also exposes all other location fields for that postal code. For example:

loc = s.get_location(reporting_type="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 allows you to capture multiple geographic levels for analysis while only reporting one primary level by default.

Country-Specific Options

Use the lower-case value in validation_type and reporting_type 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

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_type and reporting_type.
• cbsa and market may return UNKNOWN for certain ZIP codes (typically in remote areas).
• The validation_type determines the level at which the respondent must confirm their location from the provided list of options.
• The reporting_type determines the level of data included in reporting outputs.