Repository navigation
Accept Panama's 10-character postal codes and release 2.1.0 - #678
Merged
Merged
Conversation
DominiqueFlaaa
marked this pull request as draft
November 10, 2026 03:25
DominiqueFlaaa
force-pushed
the
pa-geolocated-postal-codes
branch
2 times, most recently
from
November 10, 2026 14:49
084efea to
f522ab2
Compare
DominiqueFlaaa
force-pushed
the
pa-geolocated-postal-codes
branch
from
November 10, 2026 14:51
f522ab2 to
1ee5538
Compare
DominiqueFlaaa
marked this pull request as ready for review
November 10, 2026 14:52
DominiqueFlaaa
force-pushed
the
pa-geolocated-postal-codes
branch
from
November 10, 2026 15:23
1ee5538 to
2871f97
Compare
DominiqueFlaaa
force-pushed
the
pa-geolocated-postal-codes
branch
from
November 10, 2026 15:42
2871f97 to
268a5be
Compare
rochlefebvre
approved these changes
Nov 10, 2026
rochlefebvre
left a comment
Contributor
There was a problem hiding this comment.
Looks great! Consider also allowing a space between the two postal code segments, or nothing at all. Not a blocker.
ananyaneogi
approved these changes
Nov 10, 2026
ananyaneogi
left a comment
Member
There was a problem hiding this comment.
Left one question, rest looks great
| "NP", | ||
| "NZ", | ||
| "OM", | ||
| "PA", |
Member
There was a problem hiding this comment.
Q: By removing PA from this set do we lose some shared normalizing capabilities?
Contributor
Author
There was a problem hiding this comment.
Yes, for the legacy 4-digit codes only; the 10-character codes never validated on main, so they lose nothing.
- Lookalike autocorrection (
OILZSB→011258):O815used to normalize to0815; now it's rejected and the buyer sees the validation error. Keeping it would need a length-based PA special case, and that misfires on partially typed new codes (B2S5→8255, a valid 4-digit code). The legacy codes are PO-box zones that rarely appear in shipping addresses, and the field is optional, so I'd rather surface the error than silently rewrite the input. strip_extraneous_characters: trueremoved every non-digit (0815 PANAMA→0815). That can't apply once letters are valid in PA codes.
Spaces and punctuation are still removed as before (0815, 0815. → 0815).
Panama introduced a new postal code system in May 2026. The official portal (codigospostalespanama.gob.pa) shows each code as two groups of five characters, for example K3MD7-64B34. Worldwide accepted only four digits for PA, so address forms rejected every new code, and the numeric autocorrection could turn letters into digits. Accept both formats after normalization, insert the hyphen after the fifth character, and take PA out of the numeric-only countries so that letters stay letters and forms offer a text keypad. The postal code stays optional. Bump the version to 2.1.0, refresh the lockfile and date the changelog.
DominiqueFlaaa
force-pushed
the
pa-geolocated-postal-codes
branch
from
November 10, 2026 16:17
268a5be to
28e2026
Compare
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What are you trying to accomplish?
Panama introduced a new national postal code system on 7 May 2026 (codigospostalespanama.gob.pa). Each code has 10 characters in two groups of five, for example
ADC96-M8H44. Worldwide accepts only^\d{4}$for PA, so address forms reject every new code, and the field opens a numeric keypad on phones.Public report: community.shopify.dev topic 34126.
How the new codes work
The system is geolocated: a code identifies a point on the map, not a delivery area. This is visible in the official portal's script and its public API (
/api/location?lat=…&lng=…and/api/postal/decode?code=…).23456789ABCDEFGHJKLMNPQRSTVWXZ./api/postal/decode?code=ADC96-M8H44returns 8.97093, -79.53474 (the Municipio de Panamá building, the example address inPA.yml) withprecision_meters: 3.3.What approach did you choose and why?
data/regions/PA.yml:zip_regexbecomes^(?:\d{4}|[A-Z0-9]{2}[2-9A-HJ-NP-TV-XZ]{3}[ -]?[2-9A-HJ-NP-TV-XZ]{5})$. The two groups may be separated by a hyphen, a space, or nothing (as in PL and PT);Zip.normalizestill outputs the hyphen. Characters 3–10 must use the official grid alphabet. Characters 1–2 stay broad: the first character is the zone letter (A–M today, includingI, for exampleI2), so the grid alphabet does not apply to it. Both the old 4-digit postal zone numbers and the new codes stay valid, so existing addresses are unaffected.lib/worldwide/zip.rb: addPA: [[10, "-", 5]]soZip.normalizeinserts the hyphen after the 5th character, and remove PA fromNUMERIC_ONLY_ZIP_COUNTRIESso letters are not autocorrected into digits and forms offer a text keypad.zip_requirementstaysoptional: no primary source makes the code mandatory. The decree and Gaceta Oficial publication were still pending at launch.zip_exampleand the example addresszipbecomeADC96-M8H44, the code of the example address (Municipio de Panamá, Ave. Justo Arosemena).Region#zip_typeis derived fromzip_example(any letter makes itALPHANUMERIC), so this also moves PA fromNUMERIC_AND_PUNCTUATIONtoALPHANUMERIC. That is the correct type for the new codes, and it gives forms a text keypad.The portal also accepts the 8-character grid part alone. This PR rejects that form: without the zone prefix it is not a full postal code.
Release:
lib/worldwide/version.rbgoes from 2.0.1 to 2.1.0 (minor: new accepted format),Gemfile.lockis refreshed, and the CHANGELOG[Unreleased]entries move under[2.1.0]. This also releases the street-firstaddress1formats already onmain.Test codes are real:
ADC96-M8H44(Municipio de Panamá) andACC9B-EJS3W(Biomuseo, Amador) come from/api/locationfor each building, and0815is the postal zone in the postal service's own address in the UPU addressing document for Panama ("Apartado postal 0815-01085"). Invalid cases are one-character changes ofADC96-M8H44.What should reviewers focus on?
The regex for characters 1–2 stays broad (
[A-Z0-9]{2}); characters 3–10 use the official grid alphabet.The impact of these changes
PA buyers can enter the new codes. Existing 4-digit codes stay valid.
Testing
test/worldwide/regions/pa_test.rb(7 tests, same shape asgb_test.rb,lu_test.rb,mt_test.rb,pt_test.rb) and PA rows in thenormalizeandnumeric_only_zip?tests intest/worldwide/zip_test.rb. These fail without the change.rubocopclean on changed files.Checklist