ZIP Code Lookup

📮 Look up ZIP and postal codes

Developers, data teams, and operations users can run a ZIP code lookup on one list and get structured postal identity, country, place, region, and available latitude/longitude data. Use the rows in location filters, country checks, and data cleanup workflows.

Use cases

• Check many countries in one run with International Postal Code Lookup and keep country-specific rows.
• Find a submitted ZIP value and its place details with Zip Code Finder.
• Resolve postal values to structured country and region fields with Postal Code Lookup.
• Find postal codes from a city and state or province with Zip Code Lookup by City and State.
• Check a U.S. ZIP value and its returned place data with USPS Zip Code Lookup.

📦 Returned ZIP lookup rows

Each saved dataset row represents one lookup for one postal value and country code. A row can include the postal code, country, places, region, latitude, longitude, and a found flag. The same value checked for several country codes can produce separate rows. When a postal range is expanded, each expanded value is returned as its own lookup row.

▶️ Run a ZIP code lookup

1. Choose Postal code lookup or City and state reverse lookup.
2. Add postalCodes and countryCodes, or add city, region, and countryCodes for reverse mode.
3. Choose the result detail, unmatched-value policy, sort field, and optional place limit.
4. Start the run and open the default dataset.

Use one lookup direction per run. Fields in the other Target Options section are ignored. If maxPlacesPerCode is empty, the Actor returns all available results until the source is exhausted.

⚙️ Input

The public input uses JSON or the Apify form. target and countryCodes are required; the other fields depend on the lookup direction.

Input fields

Field	Type	What it does
target	string (required)	Choose postalCodeLookup for postal or ZIP values, or cityStateLookup for a reverse lookup.
postalCodes	array of strings	Add one or more exact postal or ZIP values or numeric ranges such as 00501-00503. Leading zeros are kept. Used for postal lookup mode.
postalCodes[]	string	One exact postal or ZIP value or numeric range inside postalCodes.
maxPlacesPerCode	integer (optional)	Cap the place records returned for each postal code. Leave it empty to return all available results until the source is exhausted.
city	string (optional)	City to use for the reverse lookup.
region	string (optional)	State or province to use for the reverse lookup.
countryCodes	array of strings (required)	Add one or more ISO 3166-1 alpha-2 country codes. The same lookup values are checked for each code.
countryCodes[]	string	One ISO 3166-1 alpha-2 country code inside countryCodes.
detailLevel	string	Choose postalCode, place, or full to control how much detail each row keeps.
notFoundPolicy	string	Choose omit to leave out unmatched values or keep to save no-result records.
sortBy	string	Order returned rows by postalCode, place, region, latitude, or longitude.

This is the public input from a successful current-beta default-input run:

{
  "target": "postalCodeLookup",
  "postalCodes": [
    "10001"
  ],
  "countryCodes": [
    "US"
  ],
  "detailLevel": "full",
  "notFoundPolicy": "omit",
  "sortBy": "postalCode"
}

🧾 Output

Postal lookup and city-and-state reverse lookup use the same dataset row shape. Optional fields can be absent when the selected detail level or source data does not provide them. With notFoundPolicy set to keep, an unmatched value is saved with found: false.

Dataset fields

Field	Type	What it does
postalCode	string	Postal or ZIP value returned by the lookup.
country	string (optional)	Country name when available.
countryCode	string	ISO 3166-1 alpha-2 country code used for this row.
places	array of objects (optional)	Place details linked to the postal code when place data is included.
places[].place	string	Place name.
places[].region	string (optional)	State, province, or other region when available.
places[].latitude	number (optional)	Place latitude when available.
places[].longitude	number (optional)	Place longitude when available.
found	boolean	true when the lookup found a postal record; false for a retained no-result row.

Example matched row

This complete row came from a current-beta full-detail run:

{
  "postalCode": "10001",
  "country": "United States",
  "countryCode": "US",
  "places": [
    {
      "place": "New York City",
      "region": "New York",
      "latitude": 40.7484,
      "longitude": -73.9967
    }
  ],
  "found": true
}

With notFoundPolicy set to keep, a no-match row from the same current-beta run can look like this:

{
  "postalCode": "10001",
  "countryCode": "CA",
  "found": false
}

💳 Pricing

Pay per event

This Actor uses pay-per-event pricing. The current event price is $0.00035 for one successful postal or ZIP lookup saved to your dataset.

🔌 Integrations

Apify workflow

Run the Actor from Apify Console or the Apify API, then read the structured rows from the default dataset. You can export the dataset in the formats offered by Apify.

❓ FAQ

Can I check the same ZIP values in more than one country?

Yes. Add more than one ISO 3166-1 alpha-2 country code. The same submitted postal values are checked for each code, and each row includes the country code used.

Can I find postal codes from a city and state?

Yes. Choose City and state reverse lookup, then enter the city, state or province, and one or more country codes.

What happens when a postal value has no match?

By default, the unmatched value is omitted. Choose Keep no-result records to save its postal code and country code with found: false.

What does leaving Max places per postal code empty do?

It returns all available results until the source is exhausted. Set a positive value when you want to cap the place records for each postal code.

Can I use this for USPS address verification or ZIP code lookup by address?

No. This Actor looks up submitted postal or ZIP values and supports city-and-state reverse lookup. It is not a full street-address geocoder and does not provide USPS address verification for questions such as “what is the ZIP code for this address?”

Can it find my ZIP code from my location or Google Maps?

No. The Actor does not detect a location or read Google Maps. Submit a postal or ZIP value, or use city-and-state reverse lookup with a country code.

Do I need a source API key?

No source API key is required. Add the country code and the lookup values you want to check.

Can one postal code have more than one place?

Yes. When the source returns more than one place, the places are kept in the places array. Use maxPlacesPerCode if you want to cap that list.

Can I sort the returned rows?

Yes. Use sortBy to order rows by postal code, place, region, latitude, or longitude.

📝 Changelog

0.0: Initial release

🆘 Support

For issues, questions, or feature requests, file a ticket and I'll fix or implement it in less than 24h 🫡

🔗 Related Actors

• U.S. Census Geocoder — Match full U.S. street addresses or coordinates to Census geography when postal lookup is not enough.
• Postal Code & ZIP Lookup Scraper — Use another direct bulk postal and ZIP lookup workflow for structured place data.
• Postal Code Lookup Scraper (60+ Countries) — Resolve postal codes to places, states, and coordinates across supported countries.
• ZIP/Postal Code Lookup — Check bulk ZIP or postal values and run a city-to-postal reverse lookup.
• Postal Code Checker: Global ZIP & Postcode Lookup — Enrich country-tagged postal codes with place, region, district, and GPS fields.

Made with ❤️ by Maxime Dupré