# zipcodestack documentation > zipcodestack looks up postal/zip codes worldwide with location, distance, radius and geometry queries over a simple JSON REST API. Authenticate every request with your API key via the `apikey` query parameter or request header. Base URL: https://api.zipcodestack.com OpenAPI specification: https://zipcodestack.com/docs/openapi.yaml --- Source: https://zipcodestack.com/docs # zipcodestack.com API Documentation Use the zipcodestack.com API to validate and retrieve location information for any zip/postal code and seamlessly integrate it into your product using one of our many SDKs or other pre-built integrations. Building with an AI assistant? The full API is available as a machine-readable [OpenAPI 3.1 specification](https://zipcodestack.com/docs/openapi.yaml), and the documentation is published as [llms.txt](https://zipcodestack.com/docs/llms.txt) / [llms-full.txt](https://zipcodestack.com/docs/llms-full.txt). There is also a hosted [MCP server](https://zipcodestack.com/docs/mcp) at `https://api.zipcodestack.com/mcp` that AI agents can connect to directly. ## Getting started To get started, you have to register an API key [here](https://app.zipcodestack.com/register). Then, follow our quickstart guide or continue reading our documentation and integrate zipcodestack, using our HTTP API and dedicated client SDKs. Ultimately, [upgrade your plan](https://app.zipcodestack.com/subscription) to access all data & endpoints. --- Source: https://zipcodestack.com/docs/authentication # Authentication You'll need to authenticate your requests to access any of the endpoints in the zipcodestack.com API. In this guide, we'll look at how authentication works. zipcodestack offers two ways to authenticate your API requests: API key as `GET` parameter, or via request header. **MULTIPLE API KEYS** While our free plan only allows one API key at a time, our [paid plans](https://app.zipcodestack.com/subscription) offer multiple API keys. By using separate keys for different use cases you can track individual usage and make key rotations affect only certain parts of your application. ## GET query parameter You can pass your API key along with every request by adding it as a query parameter `apikey` **WARNING** This method could expose your API key in access logs and such. Sending the API key via a header parameter as specified below circumvents this problem. ```bash {{ title: 'Example request with authentication via get request' }} curl "https://api.zipcodestack.com/v1/status?apikey=YOUR-API-KEY" ``` Please don't commit your zipcodestack password to GitHub! ## HTTP Header The recommended way to authenticate with the zipcodestack.com API through a HTTP request header: ```bash {{ title: 'Example request with authentication via header' }} curl "https://api.zipcodestack.com/v1/status" \ -H "apikey: YOUR-API-KEY" ``` Always keep your token safe and reset it if you suspect it has been compromised. ## Using an SDK If you use one of our official SDKs, you won't have to worry about any of the above — fetch your access token from the [zipcodestack dashboard](https://app.zipcodestack.com/dashboard) and the client library will take care of the rest. All the client libraries use header authentication behind the scenes. --- Source: https://zipcodestack.com/docs/city # Search by City Endpoint On this page, we'll dive into the city search endpoint you can use to find postal codes for a specific city. This endpoint costs **1 credit per 10 postal codes** returned (minimum 1 credit). For example, 25 results = 3 credits, 100 results = 10 credits. --- ## Search Codes by City This endpoint returns all postal codes for a specified city, optionally filtered by state. ### Required attributes - **city** (string): City name. Example: Anchorage - **country** (string): Two letter country code. Example: us ### Optional attributes - **state_name** (string): State or province name to filter results. Example: Alaska - **limit** (integer): Maximum number of results to return. Example: 10 ```bash {{title: 'cURL'}} curl -G https://api.zipcodestack.com/v1/code/city?city=Anchorage&state_name=Alaska&country=us \ -H "apikey: YOUR-API-KEY" ``` ```json {{title: 'Full Response'}} { "query": { "city": "Anchorage", "state": "Alaska", "country": "us" }, "results": [ "99501", "99502", "99503", "99504", "99505" ] } ``` --- --- Source: https://zipcodestack.com/docs/coverage # Coverage Endpoint On this page, we'll dive into the coverage endpoint you can use to check postal code coverage statistics by country. This endpoint is **free** and does not consume any credits. --- ## Get Coverage Statistics This endpoint returns the number of postal codes available in our database for each country. This is a public endpoint that doesn't require authentication. ### No parameters required This endpoint doesn't require any query parameters. ```bash {{title: 'cURL'}} curl -G https://api.zipcodestack.com/v1/coverage \ -H "apikey: YOUR-API-KEY" ``` ```json {{title: 'Full Response'}} { "coverage": { "US": 41000, "DE": 16000, "AT": 3000, "GB": 27000, "FR": 25000, "...": "..." } } ``` --- --- Source: https://zipcodestack.com/docs/distance # Zip Code Distance Endpoint On this page, we'll dive into the zip code distance endpoint you can use to calculate distances between zip codes. This endpoint costs **1 credit per successful distance calculation**. For example, comparing 1 code to 5 others = 5 credits (if all codes are found). --- ## Calculate Distances Between Zip Codes This endpoint calculates the distance between a single zip code and one or more other zip codes. ### Required attributes - **code** (string): The source zip code to calculate distances from. Example: 99501 - **compare** (string): Comma-separated list of zip codes to compare distances to. Example: 90210,15106 ### Optional attributes - **country** (string): Two letter country code. Default: us - **unit** (string): Unit for distance calculation. Options: km, mi. Default: km ```bash {{title: 'cURL'}} curl -G https://api.zipcodestack.com/v1/distance?code=99501&compare=90210%2C15106&country=us&unit=km \ -H "apikey: YOUR-API-KEY" ``` ```json {{title: 'Full Response'}} { "query": { "code": "99501", "compare": [ "90210", "15106" ], "country": "us", "unit": "km" }, "results": { "90210": 3754.89, "15106": 5115.42 } } ``` --- --- Source: https://zipcodestack.com/docs/match # Match Code Pairs Endpoint On this page, we'll dive into the match code pairs endpoint you can use to find postal code pairs that are within a specified distance. This endpoint costs **1 credit** per request. --- ## Match Postal Code Pairs This endpoint returns pairs of postal codes from a given list where the distance between them is less than the specified maximum distance. ### Required attributes - **codes** (string): Comma-separated list of zip codes (max 100). Example: 99501,99502,99503 - **distance** (integer): Maximum distance between codes to be considered a match. Example: 100 - **country** (string): Two letter country code. Example: us ### Optional attributes - **unit** (string): Unit for distance calculation. Options: km, miles. Default: km ```bash {{title: 'cURL'}} curl -G https://api.zipcodestack.com/v1/match?codes=99501%2C99502%2C99503&distance=100&country=us&unit=km \ -H "apikey: YOUR-API-KEY" ``` ```json {{title: 'Full Response'}} { "query": { "codes": [ "99501", "99502", "99503" ], "distance": 100, "unit": "km", "country": "us" }, "results": [ { "code_1": "99501", "code_2": "99502", "distance": 5.23 }, { "code_1": "99501", "code_2": "99503", "distance": 8.45 }, { "code_1": "99502", "code_2": "99503", "distance": 4.12 } ] } ``` --- --- Source: https://zipcodestack.com/docs/mcp 'Connect AI agents to the zipcodestack API through our hosted MCP (Model Context Protocol) server.' # MCP Server zipcodestack ships a hosted [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, so AI agents and assistants can call the API as native tools — no SDK or glue code required. ``` https://api.zipcodestack.com/mcp ``` The endpoint speaks the streamable HTTP transport. Listing the available tools works without authentication; executing a tool requires your API key, sent as the `apikey` header. You can [get a free API key here](https://app.zipcodestack.com/register). ## Connect Using Claude Code: ```bash claude mcp add --transport http zipcodestack https://api.zipcodestack.com/mcp --header "apikey: YOUR_API_KEY" ``` Or add the server to any MCP-capable client (Claude Desktop, Cursor, VS Code, ...): ```json { "mcpServers": { "zipcodestack": { "url": "https://api.zipcodestack.com/mcp", "headers": { "apikey": "YOUR_API_KEY" } } } } ``` ## Available tools The tools are generated from the same [OpenAPI specification](https://zipcodestack.com/docs/openapi.yaml) that describes the REST API, so they always match the documented endpoints, parameters and responses. | Tool | Endpoint | Description | |---|---|---| | `search` | `GET /v1/search` | Look up postal codes | | `distance` | `GET /v1/distance` | Distance from one code to others | | `radius` | `GET /v1/radius` | Codes within a radius | | `polygon` | `POST /v1/polygon` | Codes inside a polygon | | `match` | `GET /v1/match` | Match code pairs within a distance | | `codesByCity` | `GET /v1/code/city` | Codes for a city | | `codesByState` | `GET /v1/code/state` | Codes for a state | | `provinces` | `GET /v1/country/province` | Provinces for a country | | `coverage` | `GET /v1/coverage` | Coverage by country | | `getStatus` | `GET /v1/status` | Account quota status | ## Quotas and errors Tool calls are metered exactly like REST requests: they consume your plan quota and return the same status codes and error responses (`401`, `422`, `429`, ...). If a call fails, the tool result contains the API's error message including hints on how to proceed. --- Source: https://zipcodestack.com/docs/polygon # Polygon Search Endpoint On this page, we'll dive into the polygon search endpoint you can use to find all postal codes within a custom polygon area. This endpoint costs **10 credits** per request. --- ## Find Codes Inside Polygon This endpoint returns all postal codes within a specified polygon area defined by coordinate pairs. ### Required attributes - **country** (string): Two letter country code (query parameter). Example: us - **coordinates** (array): Array of coordinate pairs [longitude, latitude] defining the polygon. Minimum 3 points required. ```bash {{title: 'cURL'}} curl -X POST https://api.zipcodestack.com/v1/polygon?country=us \ -H "apikey: YOUR-API-KEY" \ -H "Content-Type: application/json" \ -d '{ "coordinates": [ [-149.9, 61.2], [-149.8, 61.2], [-149.8, 61.3], [-149.9, 61.3], [-149.9, 61.2] ] }' ``` ```json {{title: 'Full Response'}} { "query": { "country": "us" }, "results": [ { "code": "99501", "city": "Anchorage", "state": "AK", "city_en": "Anchorage", "state_en": "Alaska", "latitude": 61.2181, "longitude": -149.9003, "distance": 0 } ] } ``` --- --- Source: https://zipcodestack.com/docs/provinces # Get Provinces Endpoint On this page, we'll dive into the provinces endpoint you can use to get a list of all states or provinces for a country. This endpoint is **free** and does not consume any credits. --- ## Get Country Provinces This endpoint returns a list of all states or provinces available for a specified country in our database. ### Required attributes - **country** (string): Two letter country code. Example: us ```bash {{title: 'cURL'}} curl -G https://api.zipcodestack.com/v1/country/province?country=us \ -H "apikey: YOUR-API-KEY" ``` ```json {{title: 'Full Response'}} { "query": { "country": "us" }, "results": [ "Alaska", "Alabama", "Arkansas", "Arizona", "California", "Colorado", "..." ] } ``` --- --- Source: https://zipcodestack.com/docs/quickstart # Quickstart This guide will get you all set up and ready to use the zipcodestack.com API. We'll cover how to get started using one of our API clients and how to make your first API request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful REST API. Before you can make requests to the zipcodestack.com API, you will need to grab your API key from your dashboard. You find it under [App » Dashboard](https://app.zipcodestack.com/dashboard). ## Choose your client Before making your first API request, you need to pick which API client you will use. In addition to cURL HTTP requests, zipcodestack offers [clients](/sdks) for JavaScript, Python, PHP and many more programming langauges. In the following example, you can see how to install each client. ```bash {{ title: 'cURL' }} # cURL is most likely already installed on your machine curl --version ``` ## Making your first API request After picking your preferred client, you are ready to make your first call to the zipcodestack.com API. Below, you can see how to send a `GET` request to the `/search` endpoint to get the latest information. ```bash {{ title: 'cURL' }} curl -G https://api.zipcodestack.com/v1/search?codes=1010&country=AT \ -H "apikey: YOUR-API-KEY" ``` ## What's next? Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further into the zipcodestack.com API: - [Grab your API key from the zipcodestack dashboard](https://app.zipcodestack.com/) --- Source: https://zipcodestack.com/docs/radius # Radius Search Endpoint On this page, we'll dive into the radius search endpoint you can use to find all postal codes within a given radius. This endpoint costs **10 credits** per request. --- ## Find Codes Within Radius This endpoint returns all postal codes within a specified radius of a given postal code. ### Required attributes - **code** (string): The postal code to search around. Example: 99501 - **radius** (integer): The radius to search within (max 500). Example: 50 - **country** (string): Two letter country code. Example: us ### Optional attributes - **unit** (string): Unit for distance calculation. Options: km, miles. Default: km ```bash {{title: 'cURL'}} curl -G https://api.zipcodestack.com/v1/radius?code=99501&radius=50&country=us&unit=km \ -H "apikey: YOUR-API-KEY" ``` ```json {{title: 'Full Response'}} { "query": { "code": "99501", "unit": "km", "radius": 50, "country": "us" }, "results": [ { "code": "99502", "city": "Anchorage", "state": "AK", "city_en": "Anchorage", "state_en": "Alaska", "distance": 5.23 }, { "code": "99503", "city": "Anchorage", "state": "AK", "city_en": "Anchorage", "state_en": "Alaska", "distance": 8.45 } ] } ``` --- --- Source: https://zipcodestack.com/docs/rate-limit # Rate Limit & Quotas You can use a certain number of requests per month, defined by your plan. Once you go over this quota, the API returns a `429` HTTP status code, and you either need to upgrade your plan or wait until the end of the month. We enforce a minute rate limit for specific plans. If you exceed this, the API returns a `429` HTTP status code. You then have to wait until the end of the minute to make more requests. Not every request counts towards your monthly request volume. Not every request counts Only successful calls count against your quota. Any error on our side or validation errors (e.g., wrong parameter) will NOT count against your quota or rate limit. ## Response Headers We attach specific headers to tell you your current monthly/minute quota and how much you have remaining in the period. ```json lines X-RateLimit-Limit-Quota-Minute: 10 X-RateLimit-Limit-Quota-Month: 300 X-RateLimit-Remaining-Quota-Minute: 5 X-RateLimit-Remaining-Quota-Month: 199 ``` --- Source: https://zipcodestack.com/docs/sdks # SDKs The recommended way to interact with the zipcodestack.com API is by using one of our official SDKs. Today, zipcodestack offers fine-tuned JavaScript, Ruby, PHP and Python libraries to make your life easier and give you the best experience when consuming the API. --- Source: https://zipcodestack.com/docs/search # Zip Code Search Endpoint On this page, we'll dive into the zip code search endpoint you can use to validate any given zip code and retrieve its location information. This endpoint costs **1 credit per postal code** found. For example, searching 5 codes that all exist = 5 credits, searching 10 codes where only 7 are found = 7 credits. --- ## Search A Zip Code This zip code search endpoint provides information about location information for the specified postal codes. ### Required attributes - **codes** (string): string. Comma-separated list of zip codes. Example: 99501,90210 ### Optional attributes - **country** (string): Two letter country code. Example: us ```bash {{title: 'cURL'}} curl -G https://api.zipcodestack.com/v1/search?codes=1010&country=AT \ -H "apikey: YOUR-API-KEY" ``` ```json {{title: 'Full Response'}} { "query": { "codes": [ "1010" ], "country": "AT" }, "results": { "1010": [ { "postal_code": "1010", "country_code": "AT", "latitude": 48.2077, "longitude": 16.3705, "city": "Wien, Innere Stadt", "state": "Wien", "city_en": "Wien, Innere Stadt", "state_en": "Wien", "state_code": "09" } ] } } ``` --- --- Source: https://zipcodestack.com/docs/state # Search by State Endpoint On this page, we'll dive into the state search endpoint you can use to find all postal codes within a specific state or province. This endpoint costs **1 credit per 10 postal codes** returned (minimum 1 credit). For example, 50 results = 5 credits, 250 results = 25 credits. Use the `limit` parameter to control costs. --- ## Search Codes by State This endpoint returns all postal codes for a specified state or province. ### Required attributes - **state_name** (string): State or province name. Example: Alaska - **country** (string): Two letter country code. Example: us ### Optional attributes - **limit** (integer): Maximum number of results to return. Example: 100 ```bash {{title: 'cURL'}} curl -G https://api.zipcodestack.com/v1/code/state?state_name=Alaska&country=us&limit=100 \ -H "apikey: YOUR-API-KEY" ``` ```json {{title: 'Full Response'}} { "query": { "state": "Alaska", "country": "us" }, "results": [ "99501", "99502", "99503", "99504", "99505", "..." ] } ``` --- --- Source: https://zipcodestack.com/docs/status # Status Endpoint The status endpoint returns information about your current quota. Requests to this endpoint do not count against your quota or rate limit. --- ## Check API Status This status endpoint returns information about your current quota. ### Response Properties - **quotas** (object): Contains information about your request quota. ```bash {{title: 'cURL'}} curl -G https://api.zipcodestack.com/v1/status \ -H "apikey: YOUR-API-KEY" ``` ```json {{title: 'Response'}} { "account_id": 313373133731337, "quotas": { "month": { "total": 300, "used": 72, "remaining": 229 }, "grace": { "total": 0, "used": 0, "remaining": 0 } } } ``` --- Source: https://zipcodestack.com/docs/status-codes # Request Status Codes You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support). A successful request will be returned with status code `200`. Before reaching out to support with an error, please be aware that 99% of all reported errors are, in fact, user errors. Therefore, please carefully check your code before contacting Protocol support. --- ## Status codes Here is a list of the different categories of status codes returned by the zipcodestack.com API. Use these to understand if a request was successful. A 200 status code indicates a successful response. A 403 status code indicates that you are not allowed to use this endpoint, [please upgrade your plan](https://app.zipcodestack.com/subscription). A 404 status code indicates that a requested endpoint does not exist. A validation error has occured. A 429 status code indicates that you have hit your rate limit or your monthly limit. For more requests [please upgrade your plan](https://app.zipcodestack.com/subscription). A 500 status code indicates a internal server error - let us know: support@zipcodestack.com --- ## Validation Errors The selected country is invalid. Should be an ISO Alpha 2 Country Code (e.g., US, DE, FR). The provided postal code format is invalid. Check that the postal code format is correct for the specified country. A required parameter is missing. Check that you've included the codes parameter in your request. --- Source: https://zipcodestack.com/docs/testing # Testing Available in plans >= medium This page includes all needed information to make sure your test environment works before deploying to production. ### Sandbox API Keys An API request sent with a sandbox api key is automatically identified as a request in sandbox mode. All request with sandbox keys will respond with dummy data. Requests done with sandbox keys do not count against your quota. Please note that the requests are still shown in the graph on the dashboard. You can select only your live key if you want to filter them out.