The Location Question allows you to collect a respondent’s location based on their postal code (zipcode). It works in two steps:
The respondent is asked to enter their postal code.
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.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
defaultvalue 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 name resolved from the ZIP | Anchorage |
County |
| County name | Anchorage Municipality |
State |
| Full state name | Alaska |
State Code |
| Two-letter USPS code | AK |
Market |
| Market/DMA label when available, otherwise | ANCHORAGE |
CBSA |
| Core-Based Statistical Area label (may be | Anchorage, AK |
Region |
| Broad US region | West |
United Kingdom
Level (human) | Use this code | What it returns | Example from dataset |
City |
| City/town resolved from the postcode | Birmingham |
Region |
| Administrative area (e.g., county/metropolitan region) | West Midlands / Bedfordshire |
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_optionsplace options at the chosen level and must select the correct one.Use the lower-case codes shown above in both
validation_typeandreporting_type.cbsaandmarketmay returnUNKNOWNfor certain ZIP codes (typically in remote areas).The
validation_typedetermines the level at which the respondent must confirm their location from the provided list of options.The
reporting_typedetermines the level of data included in reporting outputs.