Postal Code Geocoding Cache

Overview

The postal code geocoding cache system stores geographic coordinates for Canadian postal codes, enabling faster representative lookups and reducing external API calls. It integrates with the multi-provider geocoding service to provide reliable centroid calculations for postal code-based geographic queries.

Key Capabilities:

Postal code caching: Store lat/lng centroids for postal codes
Geocoding integration: Automatic geocoding via multi-provider service
Cache hit optimization: Reduce external API calls
Administrative data: City and province extraction
Representative lookup: Fast postal code → representative mapping

Use Cases:

Campaign postal code lookups
Geographic representative mapping
Postal code validation
Centroid-based spatial queries

Architecture

graph TD
    A[Campaign Service] -->|Lookup Postal Code| B[Postal Code Service]
    B -->|Check Cache| C{Cache Hit?}
    C -->|Yes| D[Return Cached Centroid]
    C -->|No| E[Geocoding Service]

    E -->|Geocode| F[Multi-Provider Geocoding]
    F -->|Parse Result| G[Extract Centroid]
    G -->|Save| H[(PostalCodeCache Model)]
    H -->|Return| D

    I[Admin] -->|View Stats| J[RepresentativesPage]
    J -->|Display| K[Cache Statistics]

    style H fill:#e1f5ff
    style F fill:#fff4e1

Database Models

PostalCodeCache Model

See PostalCodeCache Model Documentation for full schema.

Key Fields:

Field	Type	Description
`postalCode`	String	Normalized postal code (primary key)
`latitude`	Float	Centroid latitude
`longitude`	Float	Centroid longitude
`city`	String?	City name
`province`	String?	Province abbreviation

Indexes:

postalCode — Primary key, unique constraint

Related Models:

Representative — Uses postal codes for caching
Location — Uses postal codes for geocoding

API Endpoints

Admin Endpoints

Method	Endpoint	Auth	Description
GET	`/api/postal-codes/stats`	SUPER_ADMIN, INFLUENCE_ADMIN	Get cache statistics
POST	`/api/postal-codes/lookup`	SUPER_ADMIN, INFLUENCE_ADMIN	Manual postal code lookup

Public Endpoints

Postal code lookups are performed automatically via representative lookup (no direct public access).

Configuration

Environment Variables

Variable	Type	Default	Description
`GEOCODING_PROVIDER`	string	nominatim	Default geocoding provider
`GEOCODING_FALLBACK_PROVIDERS`	string	-	Comma-separated fallback providers

Admin Workflow

1. View Cache Statistics

Steps:

Navigate to Influence > Representatives
View postal code cache statistics
Monitor cache hit rate

Public Workflow

Postal code caching is automatic and transparent to public users.

Code Examples

Backend: Postal Code Caching

// api/src/modules/influence/postal-codes/postal-codes.service.ts

export class PostalCodeService {
  async getOrCreateCache(postalCode: string): Promise<PostalCodeCache> {
    const normalized = postalCode.toUpperCase().replace(/\s/g, '');

    // Check cache
    const cached = await prisma.postalCodeCache.findUnique({
      where: { postalCode: normalized }
    });

    if (cached) {
      return cached;
    }

    // Geocode postal code
    const result = await geocodingService.geocode({
      query: postalCode,
      country: 'CA'
    });

    if (!result) {
      throw new Error('Failed to geocode postal code');
    }

    // Create cache entry
    return prisma.postalCodeCache.create({
      data: {
        postalCode: normalized,
        latitude: result.latitude,
        longitude: result.longitude,
        city: result.city,
        province: result.province
      }
    });
  }
}

4.1 KiB Raw Blame History