OK to create a PR for increased accuracy of en_US zip codes?

[verdantburrito]

I was wondering what the appetite would be for updating the /locales/en_US/location/postcode_by_state.ts file data to only describe valid US postal codes.

Faker currently generates values using integer ranges by state, like so:

export default {
  AK: '{{number.int({"min": 99501,"max": 99950})}}',
  AL: '{{number.int({"min": 35004,"max": 36925})}}',
  AR: [
    '{{number.int({"min": 71601,"max": 72642})}}',
    '{{number.int({"min": 72644,"max": 72959})}}',
  ],
  AZ: '{{number.int({"min": 85001,"max": 86556})}}',
  CA: '{{number.int({"min": 90001,"max": 96162})}}',
  CO: '{{number.int({"min": 80001,"max": 81658})}}',
  CT: '0{{number.int({"min": 6001,"max": 6389})}}',

However, some of the values it generates (e.g. 02803) are simply random 5-digit integers; the United States Postal Service (USPS) doesn't recognize them:

I suspect a significant percentage of the US zipcodes generated by Faker are invalid for this reason. For example, here is the single line of code Faker currently uses to generate Rhode Island (RI) zip codes:

RI: '0{{number.int({"min": 2801,"max": 2940})}},'

However, of those 140 zipcodes, 55 of them (39%) are invalid & not recognized by the USPS:

02803,02805,02810,02811,02819,02820,02821,02834,02836,02843,02844,02845,02846,02847,02848,02849,02850,02851,02853,02854,02855,02856,02858,02866,02867,02868,02869,02870,02884,02890,02897,02899,02900,02902,02912,02913,02918,02922,02923,02924,02925,02926,02927,02928,02929,02930,02931,02932,02933,02934,02935,02936,02937,02938,02939

Here is an updated set of code that describes only the 85 valid Rhode Island (RI) zipcodes:

RI: [
  '0{{number.int({"min": 2801,"max": 2802})}}',
  '0{{number.int({"min": 2804,"max": 2804})}}',
  '0{{number.int({"min": 2806,"max": 2809})}}',
  '0{{number.int({"min": 2812,"max": 2818})}}',
  '0{{number.int({"min": 2822,"max": 2833})}}',
  '0{{number.int({"min": 2835,"max": 2835})}}',
  '0{{number.int({"min": 2837,"max": 2842})}}',
  '0{{number.int({"min": 2852,"max": 2852})}}',
  '0{{number.int({"min": 2857,"max": 2857})}}',
  '0{{number.int({"min": 2859,"max": 2865})}}',
  '0{{number.int({"min": 2871,"max": 2883})}}',
  '0{{number.int({"min": 2885,"max": 2889})}}',
  '0{{number.int({"min": 2891,"max": 2896})}}',
  '0{{number.int({"min": 2898,"max": 2898})}}',
  '0{{number.int({"min": 2901,"max": 2901})}}',
  '0{{number.int({"min": 2903,"max": 2911})}}',
  '0{{number.int({"min": 2914,"max": 2917})}}',
  '0{{number.int({"min": 2919,"max": 2921})}}',
],

The only reason I hesitate to create a pull request is that it'd require 10,006 lines of codes, instead of the 93 lines of codes in use today, to describe the set of valid, contiguous, non-gapped zipcodes for all US states. Part of that is because in trying to follow the existing code's convention, a range containing a single zipcode -- like the RI one below -- would need to be defined by its own line of code:

'0{{number.int({"min": 2804,"max": 2804})}}',

Not a big deal by itself. But when applied to all United States zipcodes, it adds up very quickly; there are 3,359 ranges that contain only a single US zipcode.

Anyway, please let me know what you think. If the number of lines of code in the file is a non-issue, then I'm worrying about nothing & I'd be happy to create the PR with the code I already have sitting locally. And if there's a more concise way I should be describing those single-zipcode ranges, please let me know -- I'm more than happy to tweak my script as needed.

[matthewmayer]

Single zip codes could just be a static string. Doesn't have to follow the previous patterns. Whatever is the most compact way to represent them makes sense

If we did this we should also modify plain zipCode (without state) to only return valid zip codes also as this is likely used more than the state version.

[verdantburrito]

Single zip codes could just be a static string. Doesn't have to follow the previous patterns. Whatever is the most compact way to represent them makes sense

Awesome. And just to be perfectly clear, this would be an acceptable (& also correct) way of registering a combination of ranges and single values in my PR?

RI: [
  '0{{number.int({"min": 2801,"max": 2802})}}',
  '02804',
  '0{{number.int({"min": 2806,"max": 2809})}}',
  '0{{number.int({"min": 2812,"max": 2818})}}',
  '0{{number.int({"min": 2822,"max": 2833})}}',
  '02835',
  '0{{number.int({"min": 2837,"max": 2842})}}',
  '02852', '02857',
  '0{{number.int({"min": 2859,"max": 2865})}}',
  '0{{number.int({"min": 2871,"max": 2883})}}',
  '0{{number.int({"min": 2885,"max": 2889})}}',
  '0{{number.int({"min": 2891,"max": 2896})}}',
  '02898', '02901'
  '0{{number.int({"min": 2903,"max": 2911})}}',
  '0{{number.int({"min": 2914,"max": 2917})}}',
  '0{{number.int({"min": 2919,"max": 2921})}}',
],

If we did this we should also modify plain zipCode (without state) to only return valid zip codes also as this is likely used more than the state version.

Could you explain what a "plain zipCode (without state)" is? I'm relatively new to using Faker, and I've interacted with generating Faker zipcodes primarily in the context of US states. I'm not sure what the changes you're alluding to are, or the files they should be made in.

[matthewmayer]

I mean, if you call faker.location.zipCode() with no parameters, it uses the patterns in
https://github.com/faker-js/faker/blob/next/src/locales/en/location/postcode.ts rather than the state-based patterns. I feel if we're going to make faker.location.zipCode({state:"foo"}) only return valid ZIP codes the same should also be true for faker.location.zipCode()? (which would require both some code and locale changes)

[verdantburrito]

I guess I'm still not clear on what code changes should I be making -- to /src/locales/en/location/postcode.ts, I assume? -- so that calls to faker.location.zipCode() with no parameters return valid zipcodes. I'd originally assumed the changes I was proposing would only affect calls to faker.location.zipCode({state:"foo"}).

Also, /src/locales/en/location/postcode.ts currently exports an array of two patterns:

export default ['#####', '#####-####'];

Which is different than the object being exported by /locales/en_US/location/postcode_by_state.ts:

export default {
  AK: '{{number.int({"min": 99501,"max": 99950})}}',
  AL: '{{number.int({"min": 35004,"max": 36925})}}',
  AR: [
    '{{number.int({"min": 71601,"max": 72642})}}',
    '{{number.int({"min": 72644,"max": 72959})}}',
  ],
  //...
}

Finally, postcode.ts appears to support generating 9-digit ZIP+4 zipcode strings, as well as 5-digit zipcode strings; postcode_by_state.ts only supports generating 5-digit zipcode strings.

[matthewmayer]

It could probably be a separate PR. Dont need to worry about it to start with.

[verdantburrito]

Great, thank you. I'll focus on getting a PR up with my changes & we'll see where that takes us.

[verdantburrito]

I created an "Issues" post to formally propose the change: #3534

[verdantburrito]

Pull request is up: #3539