Location Setup Guide

Geographic & Transport Hub Configuration

Why Locations Matter

Locations provide the geographic foundation for your travel product catalog. They enable destination-based filtering in Package Search, accurate service placement on itineraries, and proper transport hub integration for flights and rail journeys.

Key Capabilities

Hierarchical Structure: Continent → Country → Region/State → City → Area → Transport Hub
Package Filtering: Filter packages by start/end location in Package Search
Service Placement: Associate services (hotels, activities) with specific locations
Transport Integration: IATA codes for airports, station codes for rail
Content & Notes: Assign Content and Notes to locations to advise guests about location-specific travel requirements such as Visas, Health Advice, or Public Holidays that may affect their trip
Auto-Generated Names: Full location names computed from hierarchy (e.g., “Paris, France, Europe”)
Guest Advisory Content: Attach Content and Notes to a Location to inform guests about location-specific travel requirements — such as visa rules, health advice, or public holidays that may affect their trip

Typical Location Counts by Customer Type

Record Type	Small Operator	Mid-Size	Enterprise
Continents	2-4	5-7	7-9
Countries	10-30	50-100	150-250
Regions	20-50	100-200	300-500
Cities	50-200	500-2,000	5,000-10,000
Transport Hubs	20-100	200-1,000	2,000-5,000

When to Configure Locations

New Implementation: Setting up the geographic structure for a new Kaptio org
Destination Expansion: Adding new countries, regions, or cities to your catalog
Flight/Rail Integration: Setting up airports and train stations with codes
Data Migration: Importing locations from an existing system

How Locations Are Structured

Locations form a tree structure where each location has a parent. This hierarchy enables powerful filtering and automatic full location name generation.

Hierarchy Diagram

┌─────────────────────────────────────────────────────────────────────────┐
│                              CONTINENT                                   │
│                           (e.g., "Europe")                               │
│                                 │                                        │
│           ┌─────────────────────┴─────────────────────┐                 │
│           ▼                                           ▼                 │
│      ┌─────────┐                               ┌─────────┐              │
│      │ COUNTRY │                               │ COUNTRY │              │
│      │ France  │                               │  Spain  │              │
│      └────┬────┘                               └────┬────┘              │
│           │                                        │                    │
│     ┌─────┴─────┐                           ┌─────┴─────┐              │
│     ▼           ▼                           ▼           ▼              │
│  ┌───────┐  ┌─────────┐                ┌────────┐  ┌─────────┐         │
│  │REGION │  │  CITY   │                │ REGION │  │  CITY   │         │
│  │Île-de-│  │  Lyon   │                │Catalonia│ │ Madrid  │         │
│  │France │  └─────────┘                └────┬───┘  └─────────┘         │
│  └───┬───┘                                  │                          │
│      │                               ┌──────┴──────┐                   │
│      ▼                               ▼             ▼                   │
│  ┌─────────┐                    ┌─────────┐   ┌─────────┐              │
│  │  CITY   │                    │  CITY   │   │  CITY   │              │
│  │  Paris  │                    │Barcelona│   │ Girona  │              │
│  └────┬────┘                    └─────────┘   └─────────┘              │
│       │                                                                 │
│  ┌────┴────────────┐                                                    │
│  ▼                 ▼                                                    │
│ ┌──────────────┐ ┌───────────────┐                                     │
│ │TRANSPORT HUB │ │ TRANSPORT HUB │                                     │
│ │ CDG Airport  │ │ Gare du Nord  │                                     │
│ │ IATA: CDG    │ │ Train Station │                                     │
│ └──────────────┘ └───────────────┘                                     │
└─────────────────────────────────────────────────────────────────────────┘

Location Types

Record Type	Description	Typical Parent
Continent	Top-level geographic grouping	None (root)
Country	Nation state	Continent
Region	Geographic or tourism region	Country
State	Administrative division (US states, Canadian provinces)	Country or Region
City	City or town	Country, Region, or State
Area	Sub-city area or district	City
Transport Hub	Airport, train station, bus station	City or Area

Tip: When to Use Regions

Not all customers need the Region level. If your packages don’t filter by region, you can parent Cities directly to Countries. This simplifies data loading and maintenance.

Full Location Name Generation

Kaptio automatically generates the FullLocationName__c field by traversing up the hierarchy. This provides a human-readable breadcrumb:

City: Paris → "Paris, France, Europe" City: Barcelona → "Barcelona, Catalonia, Spain, Europe" City: Vancouver → "Vancouver, British Columbia, West Coast & The Rockies, Canada, North America"

Important: Max Length

The FullLocationName__c field is limited to 255 characters. Very deep hierarchies or long names may be truncated. Design your naming conventions with this in mind.

Key Fields

Field	API Name	Description
Name	Name	Location name (e.g., “Paris”, “CDG Airport”)
Parent Location	Location__c	Self-reference to parent in hierarchy
Full Location Name	FullLocationName__c	Auto-computed breadcrumb (read-only)
Location Type	LocationType__c	Airport, Train Station, Bus Station (Transport Hub only)
IATA Code	IATACode__c	3-character IATA airport code (unique)
External Code	ExternalCode__c	External system identifier (e.g., ISO country codes)
Geo Tag	GeoTag__c	GPS coordinates
Address	Address__c	Full address (for Transport Hubs)

Setting Up Geographic Locations

Geographic locations represent continents, countries, regions, states, and cities. Work top-down to ensure parent records exist before children reference them.

Prerequisites

Admin Access: System Administrator profile or permission set with Location object access
Record Types Enabled: Ensure all required record types (Continent, Country, Region, City, Transport Hub) are active
Location Hierarchy Plan: Document which geographic levels you need (some orgs skip State/Region)

Recommended Order

Step 1: Create Continents (typically 7 records)
Step 2: Create Countries (link to Continents)
Step 3: Create Regions/States (if needed, link to Countries)
Step 4: Create Cities (link to Countries or Regions)
Step 5: Create Areas (if needed, link to Cities)
Step 6: Create Transport Hubs (link to Cities or Areas)

Creating a Location Manually

Navigate to the Locations tab in Kaptio
Click New
Select the appropriate Record Type (Continent, Country, Region, City, or Area)

Screenshot: Selecting the Record Type on the New Location form

Fill in Name and Parent Location
Save

Screenshot: Completed Location form with Name and Parent Location filled in

Setting Up Transport Hubs

Transport Hubs represent physical places where passengers board or disembark — airports, train stations, and bus stations. They use the Transport Hub record type with the LocationType__c picklist to specify the hub type.

Transport Hub Types

Location Type	Description	Key Field
Airport	Commercial airports for flight integration	`IATACode__c` (required, 3-char, unique)
Train Station	Railway stations for rail packages	`ExternalCode__c` (optional, for integration)
Bus Station	Bus terminals for coach transfers	`ExternalCode__c` (optional)

Setting Up an Airport

Create the parent City first (if it doesn’t exist)
Create a new Location with Record Type: Transport Hub

Screenshot: Selecting the Transport Hub record type when creating a new Location

Set Location Type: Airport
Enter the IATA Code (3 characters, must be unique)
Set Parent Location to the City

Screenshot: New Transport Hub form with Location Type set to Airport and the IATA Code field visible

Save

Screenshot: Saved airport record showing the auto-generated Full Location Name

Example:

Name: Charles de Gaulle Airport Record Type: Transport Hub Location Type: Airport IATA Code: CDG Parent Location: Paris (City) → Full Location Name: “Charles de Gaulle Airport, Paris, France, Europe”

IATA Code Uniqueness

The IATACode__c field is configured as unique. Attempting to create two airports with the same IATA code will fail. Ensure your data is clean before loading.

Common IATA Codes

Airport	IATA	City
London Heathrow	LHR	London
Paris Charles de Gaulle	CDG	Paris
New York JFK	JFK	New York
Los Angeles International	LAX	Los Angeles
Sydney Kingsford Smith	SYD	Sydney
Tokyo Narita	NRT	Tokyo
Dubai International	DXB	Dubai

Finding IATA Codes

Use the official IATA Code Search: iata.org/code-search

Setting Up a Train Station

Create the parent City first (if it doesn’t exist)
Create a new Location with Record Type: Transport Hub
Set Location Type: Train Station
Enter External Code if integrating with rail systems
Set Parent Location to the City
Save

Example:

Name: Gare du Nord Record Type: Transport Hub Location Type: Train Station Parent Location: Paris (City) → Full Location Name: “Gare du Nord, Paris, France, Europe”

Use the station’s official name when creating rail station Location records (e.g., “London King’s Cross”, “Zürich HB”, “Roma Termini”). This keeps records recognisable and avoids duplicates caused by inconsistent abbreviations.

See Also

For how rail stations connect to transport services and pricing, see the Supplier & Service Setup Guide.

Setting Up a Bus Station

Create the parent City first (if it doesn’t exist)
Create a new Location with Record Type: Transport Hub
Set Location Type: Bus Station
Enter External Code if integrating with coach systems
Set Parent Location to the City
Save

Tips for Success

Practical advice for getting your location data right from the start.

Recommended Validations

Consider implementing these validation rules to ensure data quality:

Rule	Logic	Error Message
IATA Code Required for Airports	`RecordType.DeveloperName = 'TransportHub' && LocationType__c = 'Airport' && ISBLANK(IATACode__c)`	IATA Code is required for Airport locations
IATA Code Format	`NOT(ISBLANK(IATACode__c)) && NOT(REGEX(IATACode__c, "^[A-Z]{3}$"))`	IATA Code must be exactly 3 uppercase letters
Parent Required for Non-Continents	`RecordType.DeveloperName != 'Continent' && ISBLANK(Location__c)`	Parent Location is required for this record type
Location Type Required for Transport Hubs	`RecordType.DeveloperName = 'TransportHub' && ISBLANK(LocationType__c)`	Location Type (Airport, Train Station, etc.) is required for Transport Hubs

Duplicate Prevention

The IATACode__c field is already configured as unique in the schema. For other duplicate prevention:

Navigate to Setup → Duplicate Management → Duplicate Rules
Create a matching rule on Location combining Name + Location__c (parent)
This prevents creating “Paris” twice under the same parent Country

Naming Conventions

Use Official Names: “United Kingdom” not “UK”, “United States” not “USA” — use short codes in ExternalCode__c instead
Consistent Capitalization: “New York” not “new york” or “NEW YORK”
Avoid Abbreviations: “Saint Petersburg” not “St. Petersburg” (unless that’s the official name)
Airport Names: Include “Airport” in the name (e.g., “Heathrow Airport” not just “Heathrow”)

External Codes

Use ISO Standards: ISO 3166-1 alpha-2 for countries (FR, IT, US), ISO 3166-2 for subdivisions
Consistent Prefixes: Use prefixes like CONT-, CTY-, CITY-, HUB- to indicate record type
Uppercase: Keep codes uppercase for consistency

Hierarchy Design

Keep It Simple: Only add Region/State levels if you actually filter by them
Avoid Deep Nesting: 5-6 levels max to prevent FullLocationName truncation
Tourism vs Administrative: Design for how customers search, not administrative boundaries

Maintenance

Deactivate, Don’t Delete: If a location is no longer used, consider deactivating (custom field) rather than deleting — services may still reference it
Audit Periodically: Run queries to find orphan locations (no parent) or unused locations
Document Custom Extensions: If you add custom record types or fields, document them for future admins

Starting Small

You don’t need to load every city in the world. Start with destinations where you sell packages, cities where you have supplier services, and airports your customers commonly use. Expand as your product catalog grows.

Appendix

Bulk Loading via Data Loader

For large-scale setup, use Salesforce Data Loader or Data Import Wizard:

Prepare CSV files in hierarchy order (Continents first, then Countries, etc.)
Include RecordType.Name column (uses record type name, portable across orgs)
For parent references, use External ID or load parents first to get IDs
Load in sequence: Continents → Countries → Regions → Cities → Transport Hubs

Parent Reference Strategy

You cannot reference a parent Location that doesn’t exist yet. Either load parents first and use their Salesforce IDs, or use External IDs on both parent and child records.

CSV Templates

Use these CSV templates for bulk loading locations. Load in order: Continents → Countries → Regions → Cities → Transport Hubs.

Continents CSV Template

Name	RecordType.Name	KaptioTravel__ExternalCode__c
Africa	Continent	CONT-AF
Asia	Continent	CONT-AS
Europe	Continent	CONT-EU
North America	Continent	CONT-NA
Oceania	Continent	CONT-OC
South America	Continent	CONT-SA
Antarctica	Continent	CONT-AN

Countries CSV Template

Name	RecordType.Name	KaptioTravel__Location__r:KaptioTravel__ExternalCode__c	KaptioTravel__ExternalCode__c
France	Country	CONT-EU	CTY-FR
Italy	Country	CONT-EU	CTY-IT
Spain	Country	CONT-EU	CTY-ES
United States	Country	CONT-NA	CTY-US
Canada	Country	CONT-NA	CTY-CA

Cities CSV Template

Name	RecordType.Name	KaptioTravel__Location__r:KaptioTravel__ExternalCode__c	KaptioTravel__ExternalCode__c
Paris	City	CTY-FR	CITY-PAR
Lyon	City	CTY-FR	CITY-LYO
Rome	City	CTY-IT	CITY-ROM
Florence	City	CTY-IT	CITY-FLR
Barcelona	City	CTY-ES	CITY-BCN

Transport Hubs (Airports) CSV Template

Name	RecordType.Name	KaptioTravel__LocationType__c	KaptioTravel__IATACode__c	KaptioTravel__Location__r:KaptioTravel__ExternalCode__c
Charles de Gaulle Airport	Transport Hub	Airport	CDG	CITY-PAR
Paris Orly Airport	Transport Hub	Airport	ORY	CITY-PAR
Rome Fiumicino Airport	Transport Hub	Airport	FCO	CITY-ROM
Barcelona El Prat Airport	Transport Hub	Airport	BCN	CITY-BCN

Using External ID References

The KaptioTravel__Location__r:KaptioTravel__ExternalCode__c column references the parent by its External Code. This allows loading in sequence without needing Salesforce IDs.

Setup Checklist

Pre-Setup

Document destination regions your packages cover
Decide on hierarchy depth (do you need Regions/States?)
Gather IATA codes for airports you’ll use
Prepare source data in CSV format
Verify Record Type names match your org (Continent, Country, City, etc.)

Loading Sequence

Load Continents (verify 7 created)
Load Countries (verify count matches source)
Load Regions/States (if applicable)
Load Cities (spot-check Full Location Names)
Load Transport Hubs (verify IATA codes unique)

Validation

Verify FullLocationName__c is computed correctly
Test location lookup from Package record
Test location lookup from Service record
Verify Package Search destination filter works

Post-Setup

Assign Start/End Locations to test packages
Link test services to locations
Document any org-specific extensions

Troubleshooting

Common Issues

Full Location Name not updating — Symptom: FullLocationName__c is blank or incorrect after save.

Duplicate IATA Code error — Symptom: Error when saving airport: “Duplicate value on unique field.”

Location not appearing in Package Search filter — Symptom: A location exists but doesn’t appear as a filter option.

Parent Location lookup shows no results — Symptom: When creating a City, can’t find the Country in the parent lookup.

Data Loader: Parent reference not found — Symptom: Bulk load fails with “foreign key not found” errors.

Full Location Name exceeds 255 characters — Symptom: Deep hierarchies result in truncated FullLocationName.

Useful SOQL Queries

Find all airports

SELECT Id, Name, KaptioTravel__IATACode__c, KaptioTravel__FullLocationName__c FROM KaptioTravel__Location__c WHERE RecordType.DeveloperName = ‘TransportHub’ AND KaptioTravel__LocationType__c = ‘Airport’ ORDER BY KaptioTravel__IATACode__c

Find locations without parents (potential orphans)

SELECT Id, Name, RecordType.Name FROM KaptioTravel__Location__c WHERE KaptioTravel__Location__c = NULL AND RecordType.DeveloperName != ‘Continent’

Count locations by type

SELECT RecordType.Name, COUNT(Id) FROM KaptioTravel__Location__c GROUP BY RecordType.Name ORDER BY COUNT(Id) DESC