Technical Specifications & Data Dictionary

We use empty strings ("") rather than NULL values.

Why? Years ago, we worked with small businesses and individuals who understood "empty" but struggled with the null concept. Looking back, we probably should have stuck with NULL, but here we are. The good news: it's consistent across all fields.

Key points:

• Empty strings appear in fields where data is not applicable or cannot be determined with reasonable certainty.
• Unknown coordinates (Latitude/Longitude) are set to 0 rather than left empty.
• The ZipCode field is the only exception - it is never empty. Note it is not a primary key on its own: the file has 80,794 rows but only 41,541 distinct ZIP codes. The unique key is ZipCode + City + CityAliasName.
• When querying, check for empty strings: if (field === '' || field === null).

Developer tip: Military ZIPs (APO/FPO/DPO), PO Box ZIPs, and Unique ZIPs often have empty values for geographic fields like County, Coordinates, and Time Zone since they don't represent traditional delivery areas.

All files use UTF-8 encoding to support international characters and special symbols.

Platform-specific recommendations:

• MySQL: Use utf8mb4 character set and collation.
• PostgreSQL: Set ENCODING 'UTF8' when creating database.
• SQL Server: Use NVARCHAR data types for Unicode support.
• CSV files: UTF-8 without BOM (byte order mark).

Using UTF-8 ensures proper handling of place names with diacritics (e.g., San José, Montréal) and special characters in city alias names.

See our File Format Specifications section for detailed encoding information by format.

Approximately 23% of ZIP Codes cross county boundaries. The main database shows the primary county - the one that receives the largest volume of mail.

Business Edition includes a Multi-County supplemental file with over 22,000 records detailing all county associations for ZIPs that cross boundaries.

Supplemental file structure:

ZipCode | StateFIPS | State | CountyFIPS | County

Implementation strategies:

• Most applications: Use the primary county from the main database - it's sufficient for general purposes.
• County-level analytics: Import the supplemental file as a separate table and JOIN on ZIP when you need all county associations.
• Compliance/reporting: Use supplemental file when regulations require complete county coverage.

Coordinate system: WGS84 (World Geodetic System 1984) datum

Precision: 6 decimal places (DECIMAL(10,6))

What the coordinates represent:

• Standard ZIPs: Geographic centroid of the ZIP Code's delivery area.
• PO Box ZIPs: Location of the Post Office building (when known).
• New ZIPs: May take 60-90 days to receive coordinates as the area becomes established.
• Military ZIPs: Typically set to 0, 0 since they represent overseas locations.

Coordinate accuracy:

We only assign coordinates when we can determine them with reasonable certainty. If coordinates cannot be reliably determined, we set them to 0, 0 rather than guess. This maintains data integrity - a core principle at ZIP-Codes.com.

For GIS applications: WGS84 is compatible with Google Maps, Leaflet, Mapbox, and most modern mapping libraries. For spatial database queries, create a spatial index on the Latitude/Longitude columns for optimal performance.

Essential indexes:

• Primary Key: ZIP field + Primary (always index both when you want distinct values only).
• Most common queries: State, County, City.
• Business Edition: Add indexes on CBSACode, MSACode if querying statistical areas.
• Geospatial queries: Create spatial index on Latitude/Longitude for proximity searches.

Sample index creation (MySQL):

CREATE INDEX idx_zipcode ON zipcodes(ZipCode);
        CREATE INDEX idx_state ON zipcodes(State);
        CREATE INDEX idx_county ON zipcodes(County);
        CREATE INDEX idx_city ON zipcodes(City);
        -- For composite queries (ZipCode + Primary Record)
        CREATE INDEX idx_zip_primary ON zipcodes(ZipCode, Primary);
        -- For composite queries (State + City lookups)
        CREATE INDEX idx_state_city ON zipcodes(State, City);
        -- For geospatial (if your DB supports it)
        CREATE SPATIAL INDEX idx_coords ON zipcodes(Latitude, Longitude);

Index strategy tips:

• Don't over-index - each index adds overhead to INSERT/UPDATE operations.
• Analyze your actual query patterns and index accordingly.
• Composite indexes (multi-column) work left-to-right: (State, City) helps State-only queries, but not City-only.

Index the columns you actually filter on — ZipCode first, then State, County or City depending on your queries. A composite index on (State, City) pays for itself on address lookups.

With proper indexing, ZIP Code lookups are fast.

Performance benchmarks:

• Single ZIP lookup: Under 10ms on properly indexed tables, even under production load
• State-level queries: Sub-150ms for queries returning hundreds of results
• Full table scans: Minimal concern with only ~42,000 records
• Optimal hardware: Modern SSD storage recommended, but HDDs work fine for most use cases

Real-world example:

Our production SQL Server handles all website traffic with query times averaging under 100ms - without special performance tuning. A properly indexed table with adequate hardware can achieve significantly faster lookups.

Performance tips:

• Index your most common query fields (State, County, City).
• Use the ZIP field for lookups whenever possible (primary key = fastest).
• For high-traffic applications, consider caching frequently accessed ZIPs in memory.
• The dataset is small enough (~42K records) that entire tables can fit in database cache.

The database size itself is modest (17-55MB depending on edition), so performance bottlenecks typically come from network latency or unindexed queries, not the data volume.

Short answer: It's no longer valid.

We get this question often, and it's always investigated. The ZIP Code used to be valid but is no longer in service. The USPS revises ZIP Codes regularly to match current delivery needs. ZIP-Codes.com is a licensed USPS distributor and only publishes currently active ZIP Codes.

Common scenarios:

• The ZIP was discontinued months or years ago.
• A customer has old records that predate a ZIP Code change.
• Another website lists it because they use outdated or unverified data.
• It was a temporary or test ZIP Code that's been retired.

Verify it yourself:

Use the official USPS ZIP Code Lookup tool at https://tools.usps.com/zip-code-lookup.htm. If the USPS reports it as invalid and you believe this is an error, contact us and we'll research it immediately.

Data quality matters:

Other websites and free datasets don't adhere to the same data quality standards we do. Many use Census ZCTA data or simply never remove discontinued ZIPs. We update monthly with verified USPS data to ensure you're always working with accurate, current information.

We use real USPS ZIP Codes, not Census approximations.

ZIP Code Tabulation Areas (ZCTAs) are generalized area representations created by the U.S. Census Bureau. They only update every 10 years with each decennial census, which means they diverge from actual ZIP Code boundaries over time.

Many providers use Census ZCTA data and market it as "ZIP Codes." ZIP-Codes.com licenses true ZIP Code data directly from the USPS and updates it monthly as changes occur. When your business depends on accurate data, "close enough" isn't good enough.

Why this matters:

• ZCTAs are static for 10 years; real ZIP Codes change monthly.
• ZCTA boundaries don't match actual USPS delivery routes.
• Using ZCTAs for business decisions leads to inaccurate targeting and analysis.

The exception:

Some demographic fields (like Census population data) are only available at the ZCTA level - we clearly label these fields. To counter this limitation, we provide our own CurrentPopulation estimate calculated from active delivery points.

There are currently 41,541 active ZIP Codes in the United States and territories, as of August, 2026.

ZIP Code types (by Classification Code):

• <BLANK> - Standard: Used for general mail delivery (29,807 ZIPs).
• P - PO Box: Post Office boxes and contract delivery (9,122 ZIPs).
• U - Unique: Businesses, government agencies, universities receiving high mail volume (2,023 ZIPs).
• M - Military: APO/FPO addresses for service members overseas (589 ZIPs).

It should be noted that on occassion, a ZIP Code classified as a PO Box can also have limited street delivery as well. When this happens, you usually see some added population and demographic data.

All versions include all ZIP Code types. Each record contains a ClassificationCode field so you can filter by type or check if a ZIP has special limitations (many companies can't ship to Military ZIPs, for example).

Additional statistics:

• ~23% of ZIP Codes cross county boundaries.
• The USPS maintains 29,642 city names and aliases.
• A few rare ZIP Codes even cross state lines.

Numbers can fluctuate monthly as the USPS creates new ZIPs and discontinues old ones. View detailed ZIP Code statistics →

Because people can identify with multiple races on the Census.

Since the 2000 Census, Americans have been able to select more than one racial category. The 2010 Census alone had 63 possible race categories (6 individual races and 57 combinations). Over 9 million Americans (2.9% of the population) chose multiple races in 2010, but in 2020, 10.2% of the population chose multiple races.

How this affects the math:

• A person is counted once in the total population.
• If they select "White" and "Black," they're counted once in WhitePopulation AND once in BlackPopulation.
• When you add all race categories together, multi-racial individuals get counted multiple times.
• Therefore: Sum of race categories > Total population.

Hispanic or Latino: Hispanic or Latino is an ethnicity, not a race. This means individuals who identify as Hispanic will also be included in one of the race categories (such as White or Black). As a result, the totals shown here may exceed 100% when Hispanic is displayed alongside racial groups. Customers have explicitly asked for Hispanic Population numbers, so they are presented alongside the racial categories. However, the fact it has it's own distinct definition is usually lost. It is a critical distinction.

This applies at all geographic levels: ZIP Code, City, County, and State data all exhibit this behavior. It's not an error - it's how the Census Bureau reports race data.

Learn more about Census race and ethnicity methodology at the Census Bureau website.

Because not everyone lives in a ZIP Code.

ZIP Codes exist for mail delivery, not population enumeration. Several factors cause discrepancies between ZIP-level population sums and higher-level Census totals:

People not in ZIP Codes:

• Residents in extremely remote areas where USPS doesn't deliver mail.
• People living 20+ miles from postal facilities in rough terrain.
• These individuals are counted in County/State populations but not assigned to a ZIP Code.

Special populations:

• The Census doesn't count incarcerated individuals at their pre-incarceration ZIP Code.
• Nursing home residents may be counted at the facility, not their home ZIP.
• These populations are included in County/State totals but may not align with ZIP-level data.

Census methodology:

• The Census aggregates data at the Census Block level, then rolls up to ZIP Code Tabulation Areas (ZCTAs).
• ZCTAs don't perfectly align with actual ZIP Code boundaries.
• Small population discrepancies are expected and normal.

Bottom line: ZIP-level population sums will not match state/national totals exactly. Use ZIP Code demographics for local analysis and targeting, not for verifying Census Bureau totals.

FTP access is included with your subscription at no extra cost.

Setup process:

1. Email info@zip-codes.com with your account username.
2. We'll set up your FTP account (typically same-day, often within the hour).
3. You'll receive connection details and folder access information.
4. Configure your FTP client or automated scripts.

Connection details:

• FTP Address: ftp.zip-codes.com
• IP Address: 216.250.119.190 (static, firewall-friendly)
• Protocols: FTP, SFTP, FTPS supported
• Ports: 21 (FTP), 22 (SFTP), 990 (FTPS Implicit)
• Authentication: Username + Password (SSH keys supported)
• Access: READ-ONLY (you cannot modify server files)

Update schedule:

• Databases are published on the 1st of each month.
• Recommended: Set automated scripts for the 5th to allow for any unforeseen delays.
• Check the file's last modified date to determine if processing is needed.

Folder structure:

Each product has its own folder. You'll have access only to folders for your active subscriptions:

• ZIP-STANDARD, ZIP-DELUXE, ZIP-BUSINESS - ZIP Code databases
• ZIP-4-DELUXE, ZIP-4-STANDARD - ZIP+4 databases
• CAN-BUSINESS, CAN-DELUXE, CAN-STANDARD - Canadian postal codes
• NPANXX-DELUXE, NPANXX-STANDARD - Area code databases

For detailed FTP setup instructions and firewall configuration, visit our FTP Services Guide.

We recommend full replace for most applications.

Full Replace Method (Recommended):

• Drop existing table or truncate data
• Import new file completely
• Rebuild indexes
• Downtime: 5-30 seconds depending on database size

Why full replace works best:

• Simple and reliable
• Handles deleted ZIPs automatically
• No risk of stale data
• Fast with proper indexing

Incremental Update Method:

• Best for high-availability systems requiring zero downtime.
• Compare new file with existing data (several products have UPDATE files already prepared)
• More complex to implement but preserves foreign key relationships
• For our Update Files: DELETE obsolete records, then ADD new records. UPDATES are handled by a DELETE, followed by an ADD.

The simplest reliable update is a full reload: import the new file into a staging table, then swap it in inside a transaction. It avoids reconciling row-level changes entirely.

Updated monthly on the 1st. Our current data was last updated August 1, 2026.

Update frequency:

• 12 updates per year (published on the 1st of each month)
• Free FTP access enables automated monthly updates
• Updates reflect the latest USPS data available

Why monthly updates matter:

The USPS typically introduces 10-50 changes per month. We admit, that isn't tremendous churn, and ZIP Codes are relatively stable. However, we have multiple data sources, and those follow various update schedules - we consolidate, validate, and publish promptly. It's not only ZIP Codes you rely on, it's everything related to it. In today's business landscape, data timeliness ensures:

• Accuracy and quality in your applications
• Customer satisfaction (correct deliveries)
• Regulatory compliance
• Operational efficiency
• Effective marketing and targeting
• Competitive advantage

Need real-time data? Consider our ZIP Code API for up-to-the-minute validation and lookups.

Yes, we maintain monthly versions dating back to October 2004.

Available options:

• Single Month: Any specific publication since October 2004.
• Complete Archive: All monthly versions from 2004 to present.
• Redistribution License: Full archive with redistribution rights.

Formats available:

• CSV, Excel, Access (all dates)
• SQL scripts (available from ~2018 forward)

Use cases for historical data:

• Analyzing ZIP Code changes over time
• Validating addresses from legacy records
• Research and trend analysis
• Compliance and audit requirements

Note: Historical data reflects what was current at that point in time. Coordinates, demographics, and other fields may have been updated in subsequent months.

Purchase Historical Data →

No. ZIP Codes are mail delivery routes, not geographic divisions.

Most people think of ZIP Codes as: Nation > State > County > City > ZIP Code. This is incorrect.

What ZIP Codes actually are:

• Created exclusively for efficient mail delivery.
• Represent collections of mail delivery routes (which are collections of mailboxes)
• Change over time as USPS delivery needs or mailboxes change.
• Not required to respect City, County, or State boundaries. The USPS is a Federal Agency, just structured as a government-business hybrid and self-funding.

Real-world example:

Imagine a postal carrier placing mail in mailboxes down a long street. It would be highly inconvenient to stop and turn around at an imaginary county boundary line. The carrier continues the route to finish delivery- which means the ZIP Code crosses the county line.

Why this matters for developers:

• You cannot aggregate ZIP Code data to match official county statistics.
• You cannot use ZIP Code alone to determine County in ~23% of cases.
• City boundaries and ZIP Code boundaries rarely align.
• ZIPs can span multiple counties (even states!).
• Use ZIP Codes for delivery logistics, not geographic analysis.

For true geographic analysis, use Census Blocks, Tracts, or Counties - not ZIP Codes.

No. ZIP Codes have city names for reference, but they are not cities.

The disconnect:

• A ZIP Code may serve multiple cities, towns, or neighborhoods.
• ZIP Code boundaries do not align with city municipality boundaries.
• The "city name" on a ZIP Code is assigned by USPS for postal purposes.
• Some names are actually for local businesses or entities (Ex: Universities, Airports, Arenas, neighborhoods, government agencies, and more).

Real example: Venice, California

ZIP Code 90291 is for Venice, CA. Venice is a neighborhood within Los Angeles city limits with a population over 28,000. However:

• Venice is not an incorporated city - it's a neighborhood in Los Angeles.
• The 90291 ZIP boundary doesn't match the Venice neighborhood boundary.
• You cannot compare 90291 demographic data with Los Angeles city data - the boundaries are completely different.
• The map illustrates the disparity between boundaries. Los Angeles City Limits are shown in gray, the Venice Neighborhood Boundary in green outline, and the 90291 ZIP Code Boundary in red.

City Aliases:

Our database includes a CityAlias field listing alternate acceptable city names for mailing. Towns, villages, and well-known neighborhoods often appear here.

For developers:

• Don't assume ZIP = City in your data model
• Use the City field for USPS-preferred mailing names
• Check CityAlias for alternate acceptable names
• Never aggregate ZIP data to compare with official city statistics

Each ZIP Code is assigned one time zone based on where the majority of addresses are located.

Time zone format:

We use a numeric UTC offset system (legacy format we've maintained for compatibility):

• 4 = Atlantic (GMT -04:00)
• 5 = Eastern (GMT -05:00)
• 6 = Central (GMT -06:00)
• 7 = Mountain (GMT -07:00)
• 8 = Pacific (GMT -08:00)
• 9 = Alaska (GMT -09:00)
• 10 = Hawaii-Aleutian Islands (GMT -10:00)
• 11 = American Samoa (GMT -11:00)
• 13 = Marshall Islands (GMT +12:00)
• 14 = Guam (GMT +10:00)
• 15 = Palau (GMT +9:00)
• 16 = Micronesia (GMT +11:00)

Daylight Saving Time:

The DaylightSaving field indicates whether the ZIP observes DST:

• Y = Observes DST (most of the US)
• N = Does not observe DST (Arizona*, Hawaii, and most territories)

*Exception: The Navajo Nation in Arizona does observe DST

Edge cases:

• ZIPs on time zone boundaries: Assigned based on majority of addresses or primary county
• Military ZIPs: May have empty/zero time zone since they represent overseas locations
• USPS assignment quirks: The primary county receives the largest mail volume, which determines time zone in edge cases

Note: We don't use IANA time zone identifiers (e.g., "America/New_York"). If you need IANA format, you'll need to map our numeric codes to IANA zones in your application.

We treat county equivalents exactly like counties-no special handling required.

Some states use different terminology for their county-level divisions, but the data structure remains consistent across all states:

States with county equivalents:

• Alaska: Uses Boroughs and Census Areas instead of counties.
• Louisiana: Uses Parishes instead of counties.
• Connecticut: Transitioned from Counties to Planning Regions in 2022.
• Virginia: Has independent cities that function as county equivalents.

How we handle them:

All county equivalents receive a standard County FIPS code from the federal government and are included in our County and CountyFIPS fields just like traditional counties. You don't need to do anything special in your code - query by county name or FIPS code as normal.

Examples:

• Alaska's Anchorage Municipality appears as County: Anchorage with FIPS code 02020
• Louisiana's Orleans Parish appears as County: Orleans with FIPS code 22071
• Connecticut's Planning Regions now use new region names with updated FIPS codes and appears County: Capitol with FIPS code 09110
• Virginia's independent cities (like Alexandria) have their own FIPS codes and appears County: Fairfax City with FIPS code 51600

Connecticut's unique situation:

Connecticut eliminated county-level government in 1960 but retained counties for statistical purposes. In 2022, they officially replaced counties with Planning Regions. The U.S. Census began releasing data at the new region level in 2023. The USPS updated its ZIP Code products to use planning regions in July 2024.

This staggered rollout created significant challenges, especially for individuals unaware of the change. It was publicized, but not widely known. Our ZIP Code Database includes the new Planning Region FIPS codes and names from the USPS. However, if you're working with Connecticut data, you'll need to maintain a historical county crosswalk for relating to older datasets that still reference the legacy county structure. The Planning Regions received entirely new FIPS codes as part of the transition.

We've created a comprehensive guide with ZIP Code to Historical County crosswalks (including ZIP+4 level) to help smooth this transition. Evena cool map to see the relation of between ZIP Codes, Towns, Historical Counties, and new Planning Regions.

Read our complete guide to Connecticut's planning regions →

Bottom line: Whether it's a county, parish, borough, or planning region-we use the current federal standard. Just be aware that Connecticut requires special attention if you're integrating with historical data sources.

Yes, we offer a separate ZIP Code API service.

ZIP Code API features:

• Real-time ZIP Code validation and lookups.
• Distance calculations and Radius searches.
• Same field coverage as the database downloads.
• RESTful service with JSON and XML response formats.
• Includes both US ZIP Codes and Canadian Postal Codes.

Pricing:

The API is a separate purchase with monthly billing based on request volume:

• Free tier: 250 requests/month
• Paid tiers: $9.95 to $129.95/month (1,000 to 2M requests)
• No per-second rate limits - just monthly quotas

Database vs API - which to choose?

• Database: Best for bulk processing, internal applications, or when you need the complete dataset locally.
• API: Best for real-time validation, web forms, mobile apps, or when you need the latest data without manual updates.

Note: The API is designed for lookups and validation, not bulk data transfer. If you need all records, the database download is more efficient and cost-effective.

Learn More About the API →

Yes, all military ZIP Codes are included in every edition.

Military ZIP Code types:

• APO - Army Post Office
• FPO - Fleet Post Office (Navy)
• DPO - Diplomatic Post Office

What to expect:

Military ZIPs have basic information but lack geographic data since they represent overseas locations:

• Included: ZIP Code, City (APO/FPO/DPO), State (AE/AP/AA), Classification Code (M), Intro Date.
• Typically empty: Coordinates, County, Time Zone, City Aliases, Census data, CBSA codes.
• USPS indicators: Some USPS-specific fields like CityStateKey are populated.

For developers:

• Filter by ClassificationCode = 'M' to identify military ZIPs.
• Many shipping carriers restrict delivery to military addresses - validate business rules accordingly.
• Demographic and Geographic data is not available for these ZIPs.

Military ZIP Codes follow different rules than civilian ZIPs - they're included for completeness, but they do have limited data fields due to their unique usage. The USPS maintains these so U.S. families can send mail and packages to a local "address". They collect the mail and deliver to military transit locations who then get it to our service men and woman; whether they are on a boat, in a plane, at an overseas base, or hidden in an undisclosed bunker somewhere. P.S. We are a veteran owned business!