Introducing USPS ZIP+4 Postal Code Support for the Geocoding API

We're excited to announce a new addition to our Geocoding API: optional USPS ZIP+4 postal code support. 🎯

If you've ever wondered why some addresses need those extra four digits after the postal code, or if you've been struggling with postal code precision in your delivery or logistics apps, this feature is for you.

What Are USPS ZIP+4 Codes?

First, a quick primer. Standard US postal codes are five digits—think 90001, 20500, 78702. They identify a delivery area that can cover hundreds of buildings.

ZIP+4 codes extend this with four additional digits: 90001-1234. This precision can pinpoint a specific building, apartment complex, or even a particular mail delivery point. USPS uses these internally, and they're invaluable for:

• Delivery services needing exact address matching
• Logistics companies optimizing routes
• E-commerce platforms reducing shipping errors
• Financial institutions requiring verified address data

The New plus4_code Parameter

You can optionally request ZIP+4 data from our (reverse) geocoding endpoint.

Parameter Details:

• Name: plus4_code
• Type: Boolean
• Default: false (backward compatible ✅)
• New in: API v6

Basic Usage

The parameter is completely optional. Your existing code continues to work unchanged.

Without Plus+4 codes (existing behavior):

curl "https://api.mapbox.com/search/geocode/v6/reverse?
access_token=<YOUR_MAPBOX_ACCESS_TOKEN>&
permanent=true&
longitude=-74.088598&
latitude=40.636894"

Response:

{
   "type":"FeatureCollection",
   "features":[
      {
         "type":"Feature",
         "properties":{
            "...":"...",
            "context":{
               "address":{
                  "...":"..."
               },
               "postcode":{
                  "mapbox_id":"postcode.7931371025063902",
                  "name":"10301",
               },
               "locality":{
                  "...":"..."
               }
            }
         }
      }
   ]
}

With ZIP+4 enabled (new):

curl "https://api.mapbox.com/search/geocode/v6/reverse?
access_token=<YOUR_MAPBOX_ACCESS_TOKEN>&
permanent=true&
longitude=-74.088598&
latitude=40.636894&
plus4_code=true"

Response:

{
   "type":"FeatureCollection",
   "features":[
      {
         "type":"Feature",
         "properties":{
            "...":"...",
            "context":{
               "address":{
                  "...":"..."
               },
               "postcode":{
                  "mapbox_id":"postcode.7931371025063902",
                  "name":"10301",
                  "plus4_code":"2852"
               },
               "locality":{
                  "...":"..."
               }
            }
         }
      }
   ]
}

Quick Example

// Accessing the ZIP+4 code in your response
const plus4 = response.features[0].properties.context.postcode.plus4_code; // "2852"
const fullZip = `${postcode}-${plus4}`; // "10301-2852"

When ZIP+4 Codes Are Unavailable

Not every location has a ZIP+4 code. Rural areas, PO boxes, some commercial addresses, and locations outside the United States may not have them. When unavailable, the field will be omitted entirely from the response

Closing

Give it a try and let us know how it works for your use case. We'd love to hear your feedback in the comments!

Happy geocoding! 🗺️

Have a cool use case for Plus+4 postal codes? Share it in the comments below!