Postal Code Management

Postal codes are a foundational element of zone coverage. They provide precise, standardized geographic identifiers that customers and staff both understand. Otesse maintains a database of over 32,000 postal code records and provides tools for detecting, selecting, and visualizing postal codes within zone boundaries.

Postal Code Database

Otesse stores postal codes in a Convex table with fields for the code itself, city name, state code, latitude, longitude, and related geographic metadata. The table is indexed by state code for efficient querying. With over 32,000 records, direct full-table scans would hit Convex query limits, so the system uses targeted index queries.

Automatic Detection

When you draw a new boundary on the Coverage tab map, the system automatically detects postal codes that fall within the drawn polygon. Detection uses two parallel strategies that run simultaneously.

Bounding Box Query

The system calculates the geographic bounding box (min/max latitude and longitude) of the drawn polygon and queries for postal codes within those bounds. This is a fast, broad search that may include codes outside the actual polygon shape but within its rectangular extent.

City Name Query

The system reverse-geocodes the polygon's centroid using Mapbox to determine the city name, then queries for postal codes associated with that city. This catches codes that might be missed by the bounding box query due to irregular polygon shapes.

Results from both queries are merged and deduplicated. For new boundaries, all detected postal codes are pre-selected by default. For existing boundaries, only previously linked postal codes are shown as selected.

Postal Code Selection

The configuration drawer shows a list of detected postal codes with checkboxes. Each postal code displays its code, city name, and state. Toggle codes on or off to include or exclude them from the boundary's postal code set.

When you select a postal code, its geographic boundary polygon appears on the map as a semi-transparent blue overlay. This visual feedback helps you understand the actual area each postal code covers and whether it aligns with your intended service area.

Boundary Polygon Visualization

Selected postal code boundaries are fetched from the Geoapify API, which provides polygon shapes for US postal code areas. The system implements multiple layers of caching to keep the experience fast.

Server-Side Cache

An API route proxies requests to Geoapify with a one-hour TTL cache. This prevents redundant external API calls and reduces latency for commonly requested postal codes.

Client-Side Cache

A dedicated cache module stores fetched boundary polygons in memory during the session. When you toggle a postal code off and back on, the polygon appears instantly from the client cache without any API call.

Request Deduplication

If multiple postal codes are selected simultaneously, the system deduplicates in-flight requests to prevent fetching the same boundary polygon twice.

Postal Code Sets as Boundaries

The postal code set boundary type defines a zone's coverage entirely through postal codes rather than drawn polygons. This is the simplest approach for service areas that align with postal code boundaries. The system matches customer addresses by extracting the postal code and checking it against the set.

This approach works well for service businesses that think in terms of zip codes rather than custom geographic shapes. It is especially common for businesses transitioning from spreadsheet-based service area management where zip codes were the primary organizational unit.

Best Practices

When managing postal codes, keep these guidelines in mind. First, review auto-detected codes carefully — the bounding box query may include adjacent codes that fall outside your actual service area. Second, use the polygon visualization to verify coverage — the blue overlays show you exactly what area each postal code covers. Third, consider using postal code sets for simple service areas and drawn polygons for complex ones. Fourth, remember that postal code boundaries from Geoapify are approximations — they represent general areas, not legal postal boundaries.

Postal Codes Across Zones

Multiple zones can reference the same postal codes. When a customer's postal code matches boundaries in multiple zones, the standard priority resolution determines which zone's business rules apply. This is expected behavior for overlapping coverage areas with different service tiers.