Global Location Hierarchy

Overview

This golden config deploys a complete global location database with 7,419 records covering every country and major destination worldwide. It provides the geographic foundation that tour operators need for:

Use Case	How Locations Enable It
Itinerary Building	Link day-by-day items to specific cities and regions
Supplier Management	Map hotels, activities, and transfers to their locations
Package Search	Filter and discover packages by destination
Flight Integration	Match airports via IATA codes for GDS connections
Reporting	Analyze bookings and revenue by geography

---

What Gets Deployed

Record Type	Count	Description
Continent	8	All continents plus “Unknown” for unmapped countries
Country	212	Every country and territory worldwide
Region	67	US states, Canadian provinces, and other subdivisions
City	3,682	Cities across all countries
TransportHub	3,450	Airports with IATA codes
Total	7,419	Complete production-ready dataset

:::caution[Large Dataset - Use Data Loader] The manifest file is ~3 MB with 7,400+ records. For deployment, use Salesforce Data Loader or the Composite API rather than single-record inserts. :::

---

Geographic Coverage

By Continent

Continent	Countries	Regions	Cities	Airports
Europe	50+	12	1,200+	1,100+
North America	25+	55	800+	700+
Asia	45+	—	700+	600+
Africa	54	—	400+	350+
South America	13	—	300+	250+
Oceania	20+	—	200+	200+
Antarctica	1	—	—	—

US & Canada Detail

The United States and Canada have full state/province-level regions:

• US States: All 50 states + DC, Puerto Rico, Virgin Islands (55 regions)
• Canadian Provinces: All 13 provinces and territories
• Cities: Major and minor cities linked to their state/province

---

Hierarchy Structure

Locations form a self-referential tree using the Location__c lookup field:

graph TD
    subgraph depth [Variable Depth Hierarchy]
        C[Continent]
        CO[Country]
        R[Region]
        CI[City]
        T[TransportHub]
        
        C -->|"Location__c"| CO
        CO -->|"Location__c"| R
        CO -.->|"Direct link"| CI
        R -->|"Location__c"| CI
        CI -->|"Location__c"| T
    end

Path Examples

Full 5-level path (US cities):

North America → United States → California → Los Angeles → LAX Airport

4-level path (countries without regions):

Europe → France → Paris → CDG Airport

3-level path (cities without airports):

Africa → Morocco → Marrakech

---

Key Fields

Field	API Name	Used For
Name	Name	Display name
Parent	KaptioTravel__Location__c	Self-referential lookup to parent location
External Code	KaptioTravel__ExternalCode__c	Unique identifier for upsert operations
IATA Code	KaptioTravel__IATACode__c	3-letter airport code (TransportHubs only)
Location Type	KaptioTravel__LocationType__c	Airport, Train Station, or Bus Station

External Code Pattern

All records have unique external codes following this convention:

LOC-{TYPE}-{NAME}[-{PARENT}]

Type	Example Code
Continent	LOC-CONTINENT-EUROPE
Country	LOC-COUNTRY-FRANCE
Region	LOC-REGION-CALIFORNIA
City	LOC-CITY-PARIS-FRANCE
Airport	LOC-AIRPORT-CDG

---

Airports & IATA Codes

The dataset includes 3,450 transport hubs with IATA codes for flight system integration.

Major Hub Examples

Region	Code	Airport	City
Americas	LAX	Los Angeles International	Los Angeles
	JFK	John F. Kennedy International	New York
	ORD	O’Hare International	Chicago
	YYZ	Toronto Pearson	Toronto
	GRU	São Paulo–Guarulhos	São Paulo
Europe	LHR	London Heathrow	London
	CDG	Paris Charles de Gaulle	Paris
	FRA	Frankfurt	Frankfurt
	AMS	Amsterdam Schiphol	Amsterdam
Asia-Pacific	NRT	Narita International	Tokyo
	SIN	Singapore Changi	Singapore
	HKG	Hong Kong International	Hong Kong
	SYD	Sydney Kingsford Smith	Sydney

IATA Integration Query

SELECT Name, KaptioTravel__IATACode__c, KaptioTravel__Location__r.Name as City
FROM KaptioTravel__Location__c
WHERE RecordType.DeveloperName = 'TransportHub'
AND KaptioTravel__IATACode__c IN ('LAX', 'JFK', 'LHR', 'CDG')

---

Deployment

Order of Operations

Records must be created in hierarchical order so parent lookups resolve:

Step	Record Type	Count	Parent Lookup
1	Continents	8	None
2	Countries	212	→ Continent
3	Regions	67	→ Country
4	Cities	3,682	→ Region or Country
5	TransportHubs	3,450	→ City

Recommended Approach

1. Export to CSV - Convert manifest JSON to CSV files per record type
2. Use Data Loader - Import in order: Continents → Countries → Regions → Cities → Hubs
3. Map Record Types - Select correct record type during each import
4. External ID Upsert - Use ExternalCode__c as external ID for upsert

Prerequisites

• ✅ Kaptio package version ≥ 2.400
• ✅ All 5 Location record types active
• ✅ Create permission on Location__c
• ✅ Data Loader installed (for bulk import)

---

Verification Queries

Record Counts by Type

SELECT RecordType.DeveloperName, COUNT(Id) cnt
FROM KaptioTravel__Location__c
WHERE KaptioTravel__ExternalCode__c LIKE 'LOC-%'
GROUP BY RecordType.DeveloperName
ORDER BY RecordType.DeveloperName

Expected results:

DeveloperName	cnt
City	3,682
Continent	8
Country	212
Region	67
TransportHub	3,450

Verify Hierarchy Links

-- Check cities have valid parents
SELECT Name, KaptioTravel__Location__r.Name as Parent, 
       KaptioTravel__Location__r.RecordType.DeveloperName as ParentType
FROM KaptioTravel__Location__c
WHERE RecordType.DeveloperName = 'City'
AND KaptioTravel__ExternalCode__c LIKE 'LOC-%'
LIMIT 20

Find Orphaned Records

-- Cities without parents (should be 0)
SELECT COUNT(Id) 
FROM KaptioTravel__Location__c
WHERE RecordType.DeveloperName = 'City'
AND KaptioTravel__Location__c = null
AND KaptioTravel__ExternalCode__c LIKE 'LOC-%'

---

Common Use Cases

Find All Cities in a Country

SELECT Name, KaptioTravel__Location__r.Name as Region
FROM KaptioTravel__Location__c
WHERE RecordType.DeveloperName = 'City'
AND (KaptioTravel__Location__r.Name = 'Italy' 
     OR KaptioTravel__Location__r.KaptioTravel__Location__r.Name = 'Italy')
ORDER BY Name

Find Airports Near a City

SELECT Name, KaptioTravel__IATACode__c
FROM KaptioTravel__Location__c
WHERE RecordType.DeveloperName = 'TransportHub'
AND KaptioTravel__Location__r.Name = 'Los Angeles'

Build Full Location Path

SELECT 
  Name as City,
  KaptioTravel__Location__r.Name as RegionOrCountry,
  KaptioTravel__Location__r.KaptioTravel__Location__r.Name as Country,
  KaptioTravel__Location__r.KaptioTravel__Location__r.KaptioTravel__Location__r.Name as Continent
FROM KaptioTravel__Location__c
WHERE RecordType.DeveloperName = 'City'
AND Name LIKE 'San Francisco%'

---

Technical Notes

Self-Referential Pattern

The Location__c object references itself via the Location__c lookup field. This enables:

• Unlimited depth - Could extend beyond 5 levels if needed
• Flexible structures - Some branches deeper than others
• Single object - All location types in one object with record types

Why Record Types?

Record types provide:

• Different page layouts per level
• Validation rules specific to each type
• List views filtered by hierarchy level
• Reports grouped by location type

Handling Unmapped Countries

Countries that couldn’t be automatically mapped to a continent are linked to the “Unknown” continent. After deployment, review these and reassign:

SELECT Name FROM KaptioTravel__Location__c
WHERE RecordType.DeveloperName = 'Country'
AND KaptioTravel__Location__r.Name = 'Unknown'

---

Related Golden Configs

Config	What It Adds
Cruise Operator Foundation	Brands, channels, currencies, tax rules
B2B Trade Partner Setup	Agencies, consortia, commission agreements

---

Changelog

Version	Date	Changes
2.0.0	2026-01-13	Complete extraction: 7,419 records from production source
1.0.0	2026-01-13	Initial release with curated 261-record subset