Skip to content

Accept Panama's 10-character postal codes and release 2.1.0 - #678

Merged
DominiqueFlaaa merged 1 commit into
mainfrom
pa-geolocated-postal-codes
Nov 10, 2026
Merged

DominiqueFlaaa merged 1 commit into
mainfrom
pa-geolocated-postal-codes

Conversation

@DominiqueFlaaa

@DominiqueFlaaa DominiqueFlaaa commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

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=…).

  • Characters 1–2 are the prefix of the post office zone (estafeta) that contains the point.
  • Characters 3–10 are a grid reference computed from latitude and longitude. The grid starts at 10°N, 83.5°W and has four levels; each level adds 2 characters from the alphabet 23456789ABCDEFGHJKLMNPQRSTVWXZ.
  • The hyphen after the 5th character is display formatting only.
  • A full code resolves to a cell of about 3.3 m × 3.3 m (about 11 m²). For example, /api/postal/decode?code=ADC96-M8H44 returns 8.97093, -79.53474 (the Municipio de Panamá building, the example address in PA.yml) with precision_meters: 3.3.

What approach did you choose and why?

  • data/regions/PA.yml: zip_regex becomes ^(?:\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.normalize still 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, including I, for example I2), 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: add PA: [[10, "-", 5]] so Zip.normalize inserts the hyphen after the 5th character, and remove PA from NUMERIC_ONLY_ZIP_COUNTRIES so letters are not autocorrected into digits and forms offer a text keypad.

  • zip_requirement stays optional: no primary source makes the code mandatory. The decree and Gaceta Oficial publication were still pending at launch.

  • zip_example and the example address zip become ADC96-M8H44, the code of the example address (Municipio de Panamá, Ave. Justo Arosemena). Region#zip_type is derived from zip_example (any letter makes it ALPHANUMERIC), so this also moves PA from NUMERIC_AND_PUNCTUATION to ALPHANUMERIC. 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.rb goes from 2.0.1 to 2.1.0 (minor: new accepted format), Gemfile.lock is refreshed, and the CHANGELOG [Unreleased] entries move under [2.1.0]. This also releases the street-first address1 formats already on main.

  • Test codes are real: ADC96-M8H44 (Municipio de Panamá) and ACC9B-EJS3W (Biomuseo, Amador) come from /api/location for each building, and 0815 is 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 of ADC96-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

  • New test/worldwide/regions/pa_test.rb (7 tests, same shape as gb_test.rb, lu_test.rb, mt_test.rb, pt_test.rb) and PA rows in the normalize and numeric_only_zip? tests in test/worldwide/zip_test.rb. These fail without the change.
  • Full suite: 1497 tests, 0 failures. rubocop clean on changed files.

Checklist

  • I have added a CHANGELOG entry for this change (or determined that it isn't needed)

@DominiqueFlaaa
DominiqueFlaaa requested a review from a team as a code owner November 10, 2026 03:13
@DominiqueFlaaa
DominiqueFlaaa marked this pull request as draft November 10, 2026 03:25
@DominiqueFlaaa
DominiqueFlaaa force-pushed the pa-geolocated-postal-codes branch 2 times, most recently from 084efea to f522ab2 Compare November 10, 2026 14:49
@DominiqueFlaaa DominiqueFlaaa changed the title Accept Panama's geolocated postal codes Accept Panama's 10-character postal codes Nov 10, 2026
@DominiqueFlaaa
DominiqueFlaaa force-pushed the pa-geolocated-postal-codes branch from f522ab2 to 1ee5538 Compare November 10, 2026 14:51
@DominiqueFlaaa DominiqueFlaaa changed the title Accept Panama's 10-character postal codes Accept Panama's 10-character postal codes and release 2.1.0 Nov 10, 2026
@DominiqueFlaaa
DominiqueFlaaa marked this pull request as ready for review November 10, 2026 14:52
Comment thread data/regions/PA.yml Resolved
Comment thread data/regions/PA.yml Resolved

@rochlefebvre rochlefebvre left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great! Consider also allowing a space between the two postal code segments, or nothing at all. Not a blocker.

@ananyaneogi ananyaneogi left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left one question, rest looks great

Comment thread lib/worldwide/zip.rb
"NP",
"NZ",
"OM",
"PA",

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Q: By removing PA from this set do we lose some shared normalizing capabilities?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, for the legacy 4-digit codes only; the 10-character codes never validated on main, so they lose nothing.

  1. Lookalike autocorrection (OILZSB → 011258): O815 used to normalize to 0815; 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.
  2. strip_extraneous_characters: true removed 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
DominiqueFlaaa force-pushed the pa-geolocated-postal-codes branch from 268a5be to 28e2026 Compare November 10, 2026 16:17
@DominiqueFlaaa
DominiqueFlaaa merged commit 05a6a91 into main Nov 10, 2026
6 checks passed
@DominiqueFlaaa
DominiqueFlaaa deleted the pa-geolocated-postal-codes branch November 10, 2026 16:34

This branch was successfully deployed

1 active deployment
rubygems — 28e2026a Deployed Nov 10, 2026 by shopify-shipit[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants