# US ZIP & County to GeoJSON Polygon (`notarobot/us-zip-county-to-geojson-polygon`) Actor

Convert US ZIP/ZCTA codes and county identifiers into GeoJSON Polygon/MultiPolygon boundaries, including Apify-ready customGeolocation output.

- **URL**: https://apify.com/notarobot/us-zip-county-to-geojson-polygon.md
- **Developed by:** [Vadym Zabiiaka](https://apify.com/notarobot) (community)
- **Categories:** Developer tools, Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## US ZIP & County to GeoJSON Polygon

Turn US ZIP/ZCTA codes, county names, or county FIPS codes into GeoJSON
Polygon and MultiPolygon boundaries.

Use this Actor to:

- define service areas for franchises, delivery, sales, and field operations;
- constrain Google Maps, Places, and local lead-generation searches;
- convert county FIPS codes into map-ready boundaries;
- combine multiple ZIP/ZCTA or county areas into one territory;
- create polygons for GIS, analytics, dashboards, and interactive maps;
- generate a `customGeolocation` value for another Apify Actor.

> **ZIP/ZCTA note:** ZIP results use US Census ZIP Code Tabulation Areas
> (ZCTAs). A ZCTA is an approximate geographic representation for mapping and
> statistical analysis, not an official USPS delivery boundary. Some USPS ZIP
> Codes, including many PO Box or organization-specific codes, do not have a
> matching ZCTA.

### Quick start in Apify Console

1. Choose **ZIP/ZCTA codes** or **Counties**.
2. Paste one or more identifiers.
3. Choose the geometry detail.
4. Start the Actor.
5. Use the returned GeoJSON geometry in your map, analysis, or downstream
   Actor.

For example:

```text
10001, 02108, 90210
````

Multiple matching areas are combined into one geometry that can be passed
directly as `customGeolocation`.

### Synchronous API

Send a ZIP/ZCTA code and receive GeoJSON geometry in the same HTTP response:

```bash
curl --fail-with-body --max-time 330 \
  -X POST \
  "https://api.apify.com/v2/actors/notarobot~us-zip-county-to-geojson-polygon/run-sync?timeout=300" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "boundaryType": "zcta",
    "items": ["02108"],
    "simplification": "medium",
    "includePreviewMap": false,
    "failOnNotFound": true
  }'
```

Response:

```json
{
  "type": "Polygon",
  "coordinates": [
    [
      [-71.073444, 42.356139],
      [-71.072908, 42.355781],
      [-71.072361, 42.356402],
      [-71.073444, 42.356139]
    ]
  ]
}
```

The real response contains the complete boundary. Coordinates always follow
GeoJSON order: `[longitude, latitude]`.

Set `failOnNotFound` to `true` for API integrations so an unresolved value
fails the request instead of returning an empty or partially matched geometry.

### Supported identifiers

#### ZIP/ZCTA

Use five-digit strings:

```text
10001
02108
90210
```

#### Counties

Use a five-digit county FIPS code or a state-qualified county name:

```text
06037
Los Angeles County, CA
Los Angeles, CA
Los Angeles County California
```

Leading zeros are significant. Send `"02108"` and `"06037"` as strings, never
as the numbers `2108` or `6037`.

Bare county names are accepted only when they are unique across the United
States. The Actor does not guess ambiguous values such as `Washington County`;
add a state abbreviation or state name.

ZIP/ZCTA and county identifiers cannot be mixed in the same run. Duplicate
values are processed once.

### Geometry detail

- `none` preserves the repaired Census source detail;
- `low` applies light simplification for detailed maps;
- `medium` balances precision and payload size and is recommended for most
  integrations;
- `high` produces smaller geometry for broad territories and faster downstream
  processing.

Simplification preserves topology. The Actor does not silently truncate large
geometries.

### Practical examples

#### Local lead generation

Combine the ZIP/ZCTA codes in a sales territory and pass the returned geometry
to a Maps or Places Actor as `customGeolocation`.

#### Franchise and service areas

Merge several counties or ZIP/ZCTAs to create one operational territory for
coverage maps, routing, and territory planning.

#### County-based analytics

Convert county FIPS codes into polygons for dashboards, demographic analysis,
or joining with other county-level data.

### Data and limitations

- Boundaries come from US Census TIGER/Line 2025.
- ZIP results are Census ZCTAs, not official USPS delivery boundaries.
- Not every valid USPS ZIP Code has a matching ZCTA.
- The Actor supports US ZCTAs and counties/county equivalents only.
- It does not provide address geocoding, city boundaries, Census tracts, or
  point-in-polygon lookup.
- Very large merged territories may need `high` simplification to fit the
  limits of a downstream service.

### Troubleshooting

#### A leading zero disappeared

The identifier was serialized as a number. Send ZIP/ZCTA and FIPS identifiers
as JSON strings.

#### A valid USPS ZIP Code was not found

The delivery ZIP Code may not have a Census ZCTA. This Actor converts geographic
areas; it is not a postal-address validator.

#### A county name is ambiguous

Add the state, for example `Washington County, OR`.

#### The geometry is too large or slow downstream

Use `simplification = high` or submit fewer boundaries.

# Actor input Schema

## `boundaryType` (type: `string`):

Choose whether the pasted values are ZIP/ZCTA codes or county identifiers.

## `itemsText` (type: `string`):

Separate ZIP/ZCTA values with commas, for example: 10001, 90210, 02108. County inputs can be FIPS codes such as 06037 or state-qualified names such as Los Angeles County, CA.

## `items` (type: `array`):

Optional API-friendly array of ZIP/ZCTA codes, county FIPS codes, or county names. Combined with pasted text when both are provided.

## `outputMode` (type: `string`):

Return individual features, a merged/dissolved territory, or both.

## `simplification` (type: `string`):

Use lower detail for smaller payloads and faster downstream scrapers. Medium is recommended for Apify customGeolocation use.

## `includeProperties` (type: `boolean`):

Include boundary metadata in GeoJSON feature properties.

## `includePreviewMap` (type: `boolean`):

Generate a standalone PREVIEW.html map file in the key-value store.

## `failOnNotFound` (type: `boolean`):

Fail when any input cannot be matched. Otherwise return matched results and list unresolved inputs.

## `maxItems` (type: `integer`):

Soft maximum number of deduplicated input values to process in one run.

## Actor input object example

```json
{
  "boundaryType": "zcta",
  "itemsText": "10001, 90210, 02108",
  "items": [],
  "outputMode": "both",
  "simplification": "medium",
  "includeProperties": true,
  "includePreviewMap": true,
  "failOnNotFound": false,
  "maxItems": 500
}
```

# Actor output Schema

## `apiOutput` (type: `string`):

No description

## `dataset` (type: `string`):

No description

## `geojson` (type: `string`):

No description

## `customGeolocation` (type: `string`):

No description

## `summary` (type: `string`):

No description

## `notFound` (type: `string`):

No description

## `preview` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "itemsText": "10001, 90210, 02108"
};

// Run the Actor and wait for it to finish
const run = await client.actor("notarobot/us-zip-county-to-geojson-polygon").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "itemsText": "10001, 90210, 02108" }

# Run the Actor and wait for it to finish
run = client.actor("notarobot/us-zip-county-to-geojson-polygon").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "itemsText": "10001, 90210, 02108"
}' |
apify call notarobot/us-zip-county-to-geojson-polygon --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=notarobot/us-zip-county-to-geojson-polygon",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "US ZIP & County to GeoJSON Polygon",
        "description": "Convert US ZIP/ZCTA codes and county identifiers into GeoJSON Polygon/MultiPolygon boundaries, including Apify-ready customGeolocation output.",
        "version": "0.1",
        "x-build-id": "oozgevCKZ8DM5hBDS"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/notarobot~us-zip-county-to-geojson-polygon/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-notarobot-us-zip-county-to-geojson-polygon",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/notarobot~us-zip-county-to-geojson-polygon/runs": {
            "post": {
                "operationId": "runs-sync-notarobot-us-zip-county-to-geojson-polygon",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/notarobot~us-zip-county-to-geojson-polygon/run-sync": {
            "post": {
                "operationId": "run-sync-notarobot-us-zip-county-to-geojson-polygon",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "boundaryType"
                ],
                "properties": {
                    "boundaryType": {
                        "title": "Boundary type",
                        "enum": [
                            "zcta",
                            "county"
                        ],
                        "type": "string",
                        "description": "Choose whether the pasted values are ZIP/ZCTA codes or county identifiers.",
                        "default": "zcta"
                    },
                    "itemsText": {
                        "title": "ZIP/ZCTA codes or counties",
                        "type": "string",
                        "description": "Separate ZIP/ZCTA values with commas, for example: 10001, 90210, 02108. County inputs can be FIPS codes such as 06037 or state-qualified names such as Los Angeles County, CA.",
                        "default": ""
                    },
                    "items": {
                        "title": "Items array",
                        "type": "array",
                        "description": "Optional API-friendly array of ZIP/ZCTA codes, county FIPS codes, or county names. Combined with pasted text when both are provided.",
                        "items": {
                            "type": "string"
                        },
                        "default": []
                    },
                    "outputMode": {
                        "title": "Output mode",
                        "enum": [
                            "features",
                            "merged",
                            "both"
                        ],
                        "type": "string",
                        "description": "Return individual features, a merged/dissolved territory, or both.",
                        "default": "both"
                    },
                    "simplification": {
                        "title": "Geometry detail",
                        "enum": [
                            "none",
                            "low",
                            "medium",
                            "high"
                        ],
                        "type": "string",
                        "description": "Use lower detail for smaller payloads and faster downstream scrapers. Medium is recommended for Apify customGeolocation use.",
                        "default": "medium"
                    },
                    "includeProperties": {
                        "title": "Include GeoJSON properties",
                        "type": "boolean",
                        "description": "Include boundary metadata in GeoJSON feature properties.",
                        "default": true
                    },
                    "includePreviewMap": {
                        "title": "Generate preview map",
                        "type": "boolean",
                        "description": "Generate a standalone PREVIEW.html map file in the key-value store.",
                        "default": true
                    },
                    "failOnNotFound": {
                        "title": "Fail on not found",
                        "type": "boolean",
                        "description": "Fail when any input cannot be matched. Otherwise return matched results and list unresolved inputs.",
                        "default": false
                    },
                    "maxItems": {
                        "title": "Maximum items",
                        "minimum": 1,
                        "maximum": 5000,
                        "type": "integer",
                        "description": "Soft maximum number of deduplicated input values to process in one run.",
                        "default": 500
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```