Zippopotam.us Getting Started: API Setup & First Request (2026)

Getting started overview

Integrating with the Zippopotam.us API involves a straightforward process from account creation to your first successful API call. Zippopotam.us specializes in converting zip codes to corresponding city and state information, and vice-versa, utilizing simple RESTful endpoints and JSON responses. The service is designed for applications requiring basic geocoding functionalities.

Before making requests, developers need to register on the Zippopotam.us platform, select a plan (either the free tier or a paid subscription), and retrieve their unique API key. This key is crucial for authenticating all subsequent API calls. The API supports various lookup types, including specific zip codes, combining country and zip code, or querying by city and state. Each interaction follows standard HTTP GET request patterns, making it compatible with most programming languages and environments that can send web requests.

The API's design prioritizes ease of use, providing clear documentation on endpoint structures and expected response formats. This allows for quick implementation, particularly for projects focused on geographic data at the postal code level. Developers can expect to transition from setup to a working lookup within a short timeframe, making it suitable for rapid prototyping or integrating into existing systems without extensive overhead.

Here's a quick reference table outlining the initial steps:

Create an account and get keys

To begin using the Zippopotam.us API, the first step is to create an account. Navigate to the official Zippopotam.us homepage and follow the registration process. This typically involves providing an email address and creating a password. After successful registration, you will gain access to your personal account dashboard.

Within your dashboard, you will need to select an API plan. Zippopotam.us offers a free tier that provides 100 lookups per day, suitable for testing and low-volume applications. For higher usage, various paid tiers are available, starting at $10/month for 5,000 daily lookups. Your choice of plan directly impacts the daily request limit and the features accessible, though the core geocoding functionality remains consistent across tiers.

Once you have selected a plan, your unique API key will be generated and displayed within your account dashboard. This key is essential for authenticating your requests to the Zippopotam.us API. The API uses HTTP Basic Authentication for credentialing, where your API key serves as the username. There is no password component for API calls; the key itself acts as the complete credential. Always keep your API key secure as it directly controls access to your allocated daily lookup quota.

It is generally recommended to store API keys securely, for instance, using environment variables rather than embedding them directly in source code. This practice, common in API development, helps prevent unauthorized access and usage of your API quota. For more information on secure handling of API keys, refer to general best practices for API key management.

Your first request

Making your first request to the Zippopotam.us API is designed to be straightforward. The API's base URL is http://api.zippopotam.us. All requests are made using HTTP GET methods, and the responses are delivered in JSON format. The primary function involves resolving postal codes to geographical locations (city, state, country) or vice-versa.

To obtain information for a specific zip code, you will construct a URL in the format http://api.zippopotam.us/<country_code>/<zip_code>. For example, to look up the details for a U.S. zip code, '90210', your request URL would be http://api.zippopotam.us/us/90210.

Here’s an example using curl, a common command-line tool, to demonstrate a basic lookup for the U.S. zip code 90210:

curl -u "YOUR_API_KEY:" "http://api.zippopotam.us/us/90210"

Replace YOUR_API_KEY with the actual API key obtained from your Zippopotam.us account dashboard. Note the colon after the API key within the -u flag; this signifies an empty password, consistent with Zippopotam.us's Basic Authentication scheme. A successful response will return a JSON object containing details such as the country, country abbreviation, place name, state, state abbreviation, and latitude/longitude coordinates of the location associated with the zip code.

Example successful JSON response:

{
  "post code": "90210",
  "country": "United States",
  "country abbreviation": "US",
  "places": [
    {
      "place name": "Beverly Hills",
      "longitude": "-118.4065",
      "state": "California",
      "state abbreviation": "CA",
      "latitude": "34.0901"
    }
  ]
}

You can also query by city and state to get corresponding zip codes. The format for this request is http://api.zippopotam.us/<country_code>/<state_abbreviation>/<city_name>. For example, to find zip codes in Beverly Hills, California, use http://api.zippopotam.us/us/ca/beverly%20hills. Remember to URL-encode spaces in city names.

The Zippopotam.us API documentation provides further examples and details on various endpoint structures and data parameters, which can be useful for constructing more complex queries.

Common next steps

After successfully making your first API call, several common next steps can enhance your integration with Zippopotam.us:

1. Explore additional endpoints: The Zippopotam.us API offers various lookup methods. Beyond basic zip code lookups, explore options for querying by city and state to retrieve associated zip codes. Understanding the full range of available endpoints, as detailed in the Zippopotam.us API documentation, will allow you to leverage the service more comprehensively.

2. Integrate into your application: Move beyond curl and integrate the API calls directly into your chosen programming language. Libraries are available for most popular languages (e.g., Python's requests, Node.js's node-fetch, Java's HttpClient) that simplify sending HTTP requests and parsing JSON responses. Ensure proper error handling is implemented to gracefully manage scenarios like invalid zip codes or network issues.

3. Implement rate limiting and caching: To stay within your daily lookup limits and improve application performance, consider implementing client-side rate limiting and caching strategies. Caching frequently requested zip code data locally can reduce the number of API calls made, especially for static or rarely changing geographical information. Carefully review the Zippopotam.us pricing and usage policies to align your implementation with your chosen plan.

4. Monitor API usage: Regularly check your API usage statistics within your Zippopotam.us account dashboard. This helps you track your consumption against your plan's limits and anticipate when an upgrade might be necessary. Proactive monitoring can prevent service interruptions due to exceeding daily quotas.

5. Error handling and logging: Develop robust error handling routines for scenarios like invalid input, rate limit breaches, or internal server errors from the API. Log these errors for debugging and operational insights. The API typically returns standard HTTP status codes (e.g., 400 for bad request, 404 for not found, 429 for rate limit exceeded) which can be used to inform your application's logic.

6. Consider upgrading your plan: If your application's usage grows beyond the free tier or your current paid plan, evaluate the upgrade options available on the Zippopotam.us pricing page. Upgrading ensures uninterrupted service and access to higher daily lookup volumes.

Troubleshooting the first call

When making your first API call to Zippopotam.us, you might encounter issues. Here are common problems and their solutions:

• Incorrect API Key:

  • Symptom: Receiving an authentication error or an empty/unexpected response, potentially an HTTP 401 Unauthorized status.
  • Solution: Double-check that you have copied your API key accurately from your Zippopotam.us account dashboard. Ensure it is correctly placed in the HTTP Basic Authentication header, typically as the username with an empty password (e.g., YOUR_API_KEY:).

• Invalid URL Format:

  • Symptom: HTTP 404 Not Found error or an empty response with no relevant data.
  • Solution: Verify that the URL adheres to the expected Zippopotam.us API structure, such as http://api.zippopotam.us/<country_code>/<zip_code>. Pay close attention to country codes (e.g., us for United States) and ensure any spaces in city names are URL-encoded as %20. Consult the Zippopotam.us API documentation for correct endpoint paths.

• Exceeded Rate Limit:

  • Symptom: Receiving an HTTP 429 Too Many Requests status code.
  • Solution: This indicates you've surpassed your daily lookup limit (e.g., 100 requests for the free tier). Wait until the next 24-hour cycle or consider upgrading your Zippopotam.us plan to increase your quota. Implement caching for frequently accessed data to reduce API calls.

• Network Connectivity Issues:

  • Symptom: Request timeouts, connection refused errors, or no response at all.
  • Solution: Confirm your internet connection is active. Temporarily disable any firewalls or VPNs that might be blocking outbound HTTP requests. Test connectivity to the API domain (api.zippopotam.us) using a simple ping command.

• Parsing JSON Response:

  • Symptom: Your application receives the JSON but fails to extract data, resulting in errors like 'undefined property' or 'cannot read property of null'.
  • Solution: Ensure your JSON parsing logic correctly accounts for the structure of the Zippopotam.us response. Field names like "post code" and nested arrays like "places" require specific access patterns. Use JSON parsing tools or libraries in your programming language to inspect and navigate the response object correctly.