The address question type was born out of the need to quickly and accurately input address data into CommCare. It is a question type that provides an address lookup, which lets users select a complete address. Other questions may be configured to "subscribe" to the address question. When an address is selected, the question will "broadcast" the address's individual fields to subscribing questions, which will then be automatically filled out. In this way, one can build a form where a user selects an address and then the address's city, postal code, etc. are automatically populated into other questions.
How to Enable the Address Question Type in a Form
- Add an address lookup question to the form as a text question type, and also add any questions that will receive and populate with subparts of the address.
- Open the Advanced section of the address question.
- Under Appearance Attribute, enter "address broadcast-<topic>" where "<topic>" can be any name to identify the address (e.g. "home", "work", etc).
- Go to the address-subpart-receiving questions and under Advanced / Appearance Attribute for each of those, enter "receive-<topic>-<field>", where "<topic>" matches the address question topic name from the previous step, and "<field>" is the subpart of the address to be received by each question (e.g. "city", "zipcode", etc). The full list of available fields appears below.
- Test the new address lookup question in the app preview window to see that a selected address populates as expected and submit to save the form selections successfully.
Address Question Type Components
The address question is not a formal question type, but an appearance on a text question. When the appearance is set to 'address' on a text (by entering 'address' into the Appearance Attribute under the Advanced question fields as demonstrated above), the question appears as an address search bar.
Broadcasts will have an appearance tag of 'broadcast-<topic>' where 'topic' is a reference name that ties broadcasts to receivers (e.g. 'broadcast-hello' is tied to 'receive-hello-street'). Please note that an appearance can have multiple appearance types, so to have an address question broadcast its address components to receivers, the appearance becomes 'address broadcast-<topic>.'
Receivers will have an appearance type in the format 'receive-<topic>-<field>' where <topic> corresponds to the same topic of the broadcast.
Fields will map to the mapbox geocoder api in one of the following ways:
full: the whole address
zipcode: corresponds to 'postcode' e.g. ‘02139’
city: maps to 'place' and can be cities, towns and villages e.g. ‘Cambridge’
street: is the concatenation of 'address' and 'text' to include the address number and street name
country: maps to the 'country' e.g. ‘United States of America’
country_short: maps to the shortcode of the 'country' e.g. ‘US’
region: maps to region, which includes states, provinces, and prefectures e.g. ‘Massachusetts’
us_state: maps to the region only if it is in the US.
us_state_short: maps to the region shortcode only if it’s in the US
Receiver Question Types
The text question type is preferred for most of the components that have wide range of options such as 'street', 'zipcode', 'city'. If you have a defined set of options like 'states', consider the Multiple Choice and Multiple Choice Combobox.
Numeric question types are supported as receivers, but they are less ideal than text questions. Although they seem reasonable for zipcode, they will strip out the leading '0' (e.g. '02139' becomes '2139'). A text question with validation is better.
Multiple Choice and Multiple Choice Combobox
These questions are ideal when you want to limit the set of options, e.g. 'states'. When a broadcast is sent to a receiver, an option in the multiple choice is selected only if it matches the field it subscribes to. If there is no match, it registers a NO ANSWER as an answer. This means that if there is a previously selected answer but it receives a field that does not match its options, it will clear out the previous answer.
Special Combobox Feature: Tiered Fallbacks
It is possible to receive multiple fields and select the first match in the multiple choice combobox options. For example, if you wanted to only match on states 'CA', 'NY' and 'MA', but if none of those states match the address being received you want to fallback to match on countries 'United States of America', 'Puerto Rico', you would use 'receive-<topic>-<field1>||<field2>||<fieldn>'. An option will be selected when the first match is encountered going down the list of fields.
If an address group is used inside of a repeat group, the selected address's fields will only broadcast within that same group.
In "Project Settings", on the "Basic" page, is an option to set the project's default location:
This default location is used to set the proximity parameter, which influences search results when there are many, or ambiguous, results. For best results, select a location somewhere in your project's deployment area.