PortfolioAbout This Article
Since Shopify and POS use different address formats, storing them as-is causes issues with search and display. Japanese addresses in particular have prefecture names in different formats between English and Japanese. This article explains address data normalization.
Why Normalization is Needed
Address Format Differences Between Shopify and POS
| Field | Shopify (International Format) | POS (Japanese Format) |
|---|---|---|
| Country | Japan | - |
| Prefecture | Tokyo (English) | 東京都 (Japanese) |
| City | Shibuya | 渋谷区 |
| Address | 1-2-3 Dogenzaka | 道玄坂1-2-3 |
| Postal Code | 150-0001 | 150-0001 |
Country
Shopify (International Format)Japan
POS (Japanese Format)-
Prefecture
Shopify (International Format)Tokyo (English)
POS (Japanese Format)東京都 (Japanese)
City
Shopify (International Format)Shibuya
POS (Japanese Format)渋谷区
Address
Shopify (International Format)1-2-3 Dogenzaka
POS (Japanese Format)道玄坂1-2-3
Postal Code
Shopify (International Format)150-0001
POS (Japanese Format)150-0001
Problem: Storing as-is results in mixed "Tokyo" and "東京都"
Problems Without Normalization
| Problem | Example | Impact |
|---|---|---|
| Search mismatch | Searching '東京都' doesn't find 'Tokyo' | Customer search issues |
| Inconsistent documents | DM addresses mixed English/Japanese | Brand image degradation |
| Analysis difficulty | Same region counted separately in regional stats | Impaired business decisions |
| Delivery errors | Address format inconsistencies cause delivery issues | Reduced customer satisfaction |
Search mismatch
ExampleSearching '東京都' doesn't find 'Tokyo'
ImpactCustomer search issues
Inconsistent documents
ExampleDM addresses mixed English/Japanese
ImpactBrand image degradation
Analysis difficulty
ExampleSame region counted separately in regional stats
ImpactImpaired business decisions
Delivery errors
ExampleAddress format inconsistencies cause delivery issues
ImpactReduced customer satisfaction
Normalization Approach
Prefecture Conversion
| English | Japanese |
|---|---|
| Tokyo | 東京都 |
| Osaka | 大阪府 |
| Hokkaido | 北海道 |
| Kyoto | 京都府 |
| Aichi | 愛知県 |
| Kanagawa | 神奈川県 |
| Saitama | 埼玉県 |
| Chiba | 千葉県 |
| Hyogo | 兵庫県 |
| Fukuoka | 福岡県 |
Tokyo
Japanese東京都
Osaka
Japanese大阪府
Hokkaido
Japanese北海道
Kyoto
Japanese京都府
Aichi
Japanese愛知県
Kanagawa
Japanese神奈川県
Saitama
Japanese埼玉県
Chiba
Japanese千葉県
Hyogo
Japanese兵庫県
Fukuoka
Japanese福岡県
(All 47 prefectures defined)
Conversion rules:
- Exact match conversion
- Case insensitive
- Keep original value if not found
Conversion Process Flow
Get Shopify Address
Retrieve customer address information from Shopify
Convert Prefecture
Convert English notation to Japanese notation
Combine Address
Combine prefecture, city, and street address
Save to POS
Save normalized address to POS
Conversion Details
Full Address Normalization
Address Normalization Example
Input (Shopify Format)
Province: Tokyo, City: Shibuya, Address1: 1-2-3 Dogenzaka, Address2: ABC Building 5F
Conversion Process
Province: Tokyo → 東京都, City: As-is, Address: Keep original value
Output (POS Format)
Address: 東京都 Shibuya 1-2-3 Dogenzaka ABC Building 5F
Note: Perfect Japanese conversion is difficult, so prioritize prefecture conversion and keep other values as input
Conversion Table Example
| English | Japanese | Note |
|---|---|---|
| Tokyo | 東京都 | Metropolis |
| Osaka | 大阪府 | Prefecture |
| Kyoto | 京都府 | Prefecture |
| Hokkaido | 北海道 | Territory |
| Aichi | 愛知県 | Prefecture |
| Fukuoka | 福岡県 | Prefecture |
| Okinawa | 沖縄県 | Prefecture |
Tokyo
Japanese東京都
NoteMetropolis
Osaka
Japanese大阪府
NotePrefecture
Kyoto
Japanese京都府
NotePrefecture
Hokkaido
Japanese北海道
NoteTerritory
Aichi
Japanese愛知県
NotePrefecture
Fukuoka
Japanese福岡県
NotePrefecture
Okinawa
Japanese沖縄県
NotePrefecture
Implementation Considerations
Handling Unconvertible Cases
| Case | Input Example | Handling | Reason |
|---|---|---|---|
| Province is empty | Province = "" | Save as empty | May not be a required field |
| Not in conversion table | Province = "Toky" (typo) | Save original value | Better to keep original than convert incorrectly |
| Non-Japan address | Country = "United States" | Save without conversion | No need to convert to Japanese format |
Province is empty
Input ExampleProvince = ""
HandlingSave as empty
ReasonMay not be a required field
Not in conversion table
Input ExampleProvince = "Toky" (typo)
HandlingSave original value
ReasonBetter to keep original than convert incorrectly
Non-Japan address
Input ExampleCountry = "United States"
HandlingSave without conversion
ReasonNo need to convert to Japanese format
Bidirectional Considerations
| Sync Direction | Conversion Content |
|---|---|
| Shopify → POS | Convert English → Japanese |
| POS → Shopify | Convert Japanese → English (when needed) |
Shopify → POS
Conversion ContentConvert English → Japanese
POS → Shopify
Conversion ContentConvert Japanese → English (when needed)
Considerations:
- Conversion is not reversible ("渋谷区" → "Shibuya" is complex)
- Store original data in separate field (original_address metafield, etc.)
- Basically one-way from Shopify → POS
Maintaining Data Quality
Validation Rules
| Field | Rule | Error Handling |
|---|---|---|
| Postal code | 7-digit number (remove hyphens) | Warning log, save value |
| Prefecture | Exists in conversion table | Save original if conversion fails |
| Full address | Not empty | Warning log if empty |
Postal code
Rule7-digit number (remove hyphens)
Error HandlingWarning log, save value
Prefecture
RuleExists in conversion table
Error HandlingSave original if conversion fails
Full address
RuleNot empty
Error HandlingWarning log if empty
Logging and Monitoring
| Log Item | Normal Case | Conversion Failure Case |
|---|---|---|
| type | address_normalization | address_normalization |
| status | success | partial_failure |
| input.province | Tokyo | Toky |
| output.prefecture | 東京都 | Toky |
| warning | - | Province not found in conversion table |
type
Normal Caseaddress_normalization
Conversion Failure Caseaddress_normalization
status
Normal Casesuccess
Conversion Failure Casepartial_failure
input.province
Normal CaseTokyo
Conversion Failure CaseToky
output.prefecture
Normal Case東京都
Conversion Failure CaseToky
warning
Normal Case-
Conversion Failure CaseProvince not found in conversion table
Monitoring alert: Notify when conversion failure rate exceeds threshold
Operational Notes
Customer Address Changes
Address Change Handling
Customer changes address
Customer updates address in Shopify My Page
Catch change event
Detect change via Webhook
Normalize new address
Apply English → Japanese conversion
Update POS address
Save normalized address to POS
Considerations:
- Change timing (real-time or batch)
- Conflict possibility (simultaneous change at store)
- History retention (keep old address for delivery history)
Allowing Manual Corrections
Example of imperfect auto-conversion: "東京都 Shibuya 1-2-3"
| Method | Details |
|---|---|
| Manual correction in POS admin | Admin corrects to proper address |
| Prioritize manual value after correction | Prioritize manual correction over auto-sync |
| Prevent overwrite | Consider setting to not overwrite on next sync |
Manual correction in POS admin
DetailsAdmin corrects to proper address
Prioritize manual value after correction
DetailsPrioritize manual correction over auto-sync
Prevent overwrite
DetailsConsider setting to not overwrite on next sync
Operational rules:
- Manual correction OK for obvious errors
- Keep record of corrections
- Enable "Protect manual corrections" in sync settings
Benefits of This Normalization
Data Quality
- Prefectures stored in unified format
- Search and aggregation work accurately
- Improved document output quality
Operational Efficiency
- Reduced address-related inquiries
- Prevention of delivery issues
- Regional analysis becomes possible