# Zippopotam.us MCP > Zippopotam.us delivers global postal code intelligence directly through your AI agent. It instantly translates any zip or postal code into precise geographical data, pulling out city names, state details, and latitude/longitude coordinates for over 60 countries. Use this to validate addresses, calculate service areas, or build location-aware workflows without leaving your chat window. ## Overview - **Category:** artificial-intelligence - **Price:** Free - **Tags:** postal-code-lookup, geographic-data, json-api, latitude-longitude, location-intelligence, reverse-geocoding, global-data ## Description This MCP gives your agent the intelligence needed to handle global addressing. Instead of needing a separate database query or relying on limited internal lists, you can ask it for location details using just a postal code. You get back structured data: the city, the state, and exact coordinates for that spot. Need to check if Miami has three different zip codes? It handles that. Working with complex supply chains, your agent acts like a dedicated geographic specialist. This is especially powerful when you combine it with other services; for example, chaining this MCP with a billing system MCP allows your agent to validate both the location and the service address in one go. Because all these operations run on Vinkius, you get full visibility into what data flowed through every step of the process using Vinkius AI Analytics. This means nothing happens in the dark; you always know exactly which coordinates were used and how the budget is being spent. ## Tools ### lookup_nearby_city Finds all associated postal codes when given a general city and state name. ### lookup_postcode Retrieves the full location details, including coordinates, for any specific zip code. ## Prompt Examples **Prompt:** ``` Find the city and state for zip code 90210 in the US. ``` **Response:** ``` The zip code 90210 corresponds to Beverly Hills, California (CA). I also have the exact coordinates: Latitude 34.0901, Longitude -118.4065. ``` **Prompt:** ``` Lookup the postal code 'SW1A 1AA' in Great Britain. ``` **Response:** ``` In Great Britain (GB), the postal code SW1A 1AA corresponds to London, England. This is the area for Buckingham Palace. The coordinates are 51.501, -0.1419. ``` **Prompt:** ``` List all postal codes for 'Miami', Florida (FL). ``` **Response:** ``` Retrieving data for Miami... I've found a large list of zip codes including 33101, 33109, 33125, and many others. Would you like me to list them all or focus on a specific neighborhood? ``` ## Capabilities ### Determine Coordinates by Zip You pass a postal code, and it returns the precise latitude and longitude for that location. ### Find Codes for a City You list a city and state, and it compiles all associated postal codes for that area. ### Validate Global Addresses The agent cross-references an address against global data to confirm the validity of the zip code and location details. ## Use Cases ### Checking a new market's feasibility A regional sales manager needs to know the service boundaries for a new state. They ask their agent to use `lookup_nearby_city` with the city name, which returns all relevant postal codes. This shows them exactly what zip code ranges they need to target, saving days of manual research. ### Validating billing addresses for a client A finance ops engineer receives an invoice with a suspicious zip code. They prompt their agent using `lookup_postcode`. The agent quickly confirms the location is not only valid but also provides the coordinates, allowing the engineer to flag it immediately before processing payment. ### Fulfilling complex international orders A global e-commerce developer needs a checkout field that validates addresses across multiple countries. They use this MCP's data to ensure every provided postal code matches known city and state boundaries, preventing failed shipments. ### Calculating distance for delivery zones A dispatch coordinator determines if a new client falls within the service zone. They ask their agent to get coordinates using `lookup_postcode`, which provides the necessary lat/long pair to run an accurate distance calculation. ## Benefits - Validate addresses on the fly: Use `lookup_postcode` to immediately confirm a zip code's city, state, and exact coordinates for any global location. - Map out service areas: If you need to know every possible postal code in a given region, use `lookup_nearby_city` instead of manually searching through lists. - Build complex workflows: Connect this MCP with others—say, messaging or billing services. Your agent can validate an address and then automatically create a support ticket for that specific location. - No API keys needed: This service is public access, so you never have to worry about managing credentials; your AI client connects once and gets the data. - Structured results always: You don't get messy text. You get clean JSON with latitude and longitude points ready for database insertion or mapping tools. ## How It Works The bottom line is you get reliable, actionable geographic facts without writing any API calls or managing keys yourself. 1. Connect this MCP to your AI client on Vinkius. 2. Prompt your agent with a specific query, like 'What's the coordinate for X postal code?' 3. Your agent runs the lookup and returns structured data: city name, state, latitude, and longitude. ## Frequently Asked Questions **How does lookup_postcode work?** It takes a specific postal code and returns all associated geographic data points. This means you get the city, state, and exact latitude/longitude for that number. **Can Zippopotam.us list all zip codes in a big metro area?** Yes, use `lookup_nearby_city`. You simply provide the desired city name and state, and it pulls back a full list of associated postal codes for you. **Do I need an API key to use Zippopotam.us?** No. This MCP uses public access, meaning there's no key management required from your end—just connect it to your AI client and start querying. **What is the difference between the two tools?** Use `lookup_postcode` when you have a specific zip code and need its details. Use `lookup_nearby_city` when you have a general area (city/state) and want to find all relevant zip codes. **What happens if I use `lookup_postcode` with an invalid or non-existent postal code?** The tool handles invalid inputs gracefully by returning a specific error object. Your agent will receive this failure report, allowing it to continue running the workflow without crashing and prompting you to check your input data. **Does `lookup_nearby_city` or `lookup_postcode` output the geographic data in a structured format?** Yes. All results are returned as clean, usable JSON objects. This structure makes it easy for your AI client to read and pass the latitude, longitude, state name, or coordinates directly into another connected MCP. **Are there any rate limits when calling Zippopotam.us tools?** The platform manages usage, but sustained high-volume requests are subject to standard API rate limits. If you exceed the allowed calls in a window, your agent will receive an explicit error code, which helps manage retries and throttling. **How can I combine data from `lookup_nearby_city` with other operational tasks?** You get precise coordinates for any city found. You can pass these latitude and longitude values immediately to a separate logistics MCP or mapping service to calculate routes, check service areas, or validate distances. **Can I lookup a US zip code and get its coordinates?** Yes! Use the `lookup_postcode` tool with the country 'US' and the zip code. It will return the city, state, and coordinates for that location. **Which countries are supported by Zippopotam.us?** Zippopotam.us supports over 60 countries, including the US, Canada, Great Britain, Brazil, France, Germany, and many others. You can use the standard 2-letter ISO country codes. **Can I find all zip codes for a specific city?** Yes! Use the `lookup_city` tool with the country code, state, and city name. It will return a list of all postal codes associated with that urban area.