Countries, states, cities

Every address in GCM — member home address, group meeting location, ministry venue, school campus — picks from three cascading dropdowns: Country → State / Province → City. The values come from three reference tables (countries, states, cities) and the lists are platform-managed, so you'll see the same options whether you're a 50-member plant in Belize or a 5,000-member network in Brazil.

This article walks through where they show up, how the cascade works, what's pre-loaded, and what platform admins do behind the scenes.

Where geography surfaces

The country / state / city dropdowns appear in:

• Member profile — home address fields.
• Group / ministry profile — meeting venue.
• School campus — physical location.
• Visitor form — public-facing "where are you from?" field.
• Org settings — the church's own address.
• Map module — addresses are geocoded and pinned, then clustered by city / state.

Each table holds the human-readable name plus an ISO code so the geocoding edge function and downstream analytics speak in a standard.

The cascade

The three tables are linked by foreign keys:

countries  ← states (country_id)  ← cities (state_id, country_id)

In the UI, picking a country narrows the state dropdown to states in that country, and picking a state narrows the city dropdown. Pick Jamaica and the state dropdown shows the 14 parishes; pick Saint Andrew and the city dropdown shows Kingston, Half Way Tree, etc.

If your country uses provinces instead of states or departments instead of provinces, the column for that level is the same — the platform reference table stores admin_level_label per country so the UI can render "Province" in Canada and "State" in the United States without a code change.

Why this is platform-managed

Three reasons:

1. Geocoding consistency. GCM's map module calls a geocoding service (Nominatim by default, optionally Google or Mapbox). The service expects canonical country and state names — if church A spells Saint Andrew and church B spells St Andrew, the geocoder gives back two different lat/lons and the map looks broken.
2. Cross-tenant statistics. Platform analytics roll member counts by country and state. Free-text would make those totals meaningless.
3. i18n. Each country has translations into English, Spanish, Portuguese, French — owning the list lets the platform keep those translations clean.

You won't see countries / states / cities on the org-level Reference Data page. They live behind Platform Admin → Geography, accessed only by GCM staff.

What's pre-loaded

At seed time the platform loads:

• Every country — all 195 countries plus dependent territories, with ISO 3166-1 alpha-2 codes, dial codes, and flag emojis.
• States / provinces / regions — for every country, the top-level administrative divisions.
• Cities — a starter list of the largest 30-50 cities per country.

If your address dropdown is missing a city — particularly common for small towns or recently incorporated areas — the path is to request an addition via support, or have a platform admin add it directly through the geography tab (see Adding states or cities below).

Adding states or cities

This is platform-admin work but it's worth knowing how it happens so you can request additions efficiently.

The platform admin opens Platform Admin → Geography and sees a three-panel cascade: Countries on the left, States in the middle, Cities on the right. Clicking a country loads its states; clicking a state loads its cities.

For one or two additions they click the + button next to the panel header, fill in the name (and ISO code for states), save.

CSV bulk import

For a fresh country rolling out a large list — say, all 50 US states or 200 Brazilian municipalities — there's a CSV bulk import.

1. Select the country (for states) or state (for cities) on the left.
2. Click Upload on the panel header.
3. Paste lines into the import textarea, one per line:
   • States: name,iso_code (the ISO code defaults to the first 3 letters of the name if omitted)
   • Cities: name
4. Lines starting with # are ignored. Blank lines are ignored.
5. Click Import.

Behind the scenes it does a single INSERT round-trip; the table's unique index means re-importing the same list is a no-op for rows that already exist. A typical import of 50 US states is sub-second.

Example states import for the United States:

# US states — full list
Alabama,AL
Alaska,AK
Arizona,AZ
# ...

How the org admin should handle a missing city

You don't have edit access, but here's the workflow:

1. Member adds the city as a free-text override. The member profile has a fallback "City (free text)" field that's used when the dropdown doesn't cover it. The geocoder still works because it falls back to the free-text city.
2. You email support with the country, state, and city name to add.
3. Platform staff adds it within a few business days, the dropdown picks it up automatically, and the next time the member is edited their record can be moved from the free-text fallback to the canonical city.

The member's geocoded lat/lon survives the move because it's stored on the member row directly, not on the city.

Country fields beyond name

Each country row has more than just a name:

Column	Example	Used for
iso_code	JM	Geocoding, phone validation, integrations
iso_numeric	388	Banking, BIC routing
dial_code	+1	Phone field auto-prefix in the visitor form
flag_emoji	🇯🇲	Visual decoration in dropdowns
admin_level_label	Parish	What to call the second-level division in the UI

You'll see the flag emoji in the country dropdown and the dial code prefilled on phone inputs — that's where these extra fields show up to the end user.

Translations

Countries, states, and cities all support the translations JSONB column. The platform pre-fills English; Spanish and Portuguese translations are loaded for the largest 30+ countries. If a translation is missing the UI falls back to the English name. See Multilingual labels.

Next

• Multilingual labels — how country / state / city names are rendered per locale.
• Customize member types — back to the lists you fully own.