Nj Api

Adapter implementation for the New Jersey Office of GIS geocoding and address suggestion services.

NJ Geocoding API Adapter (adapters/nj-api/)

Adapter implementation for the New Jersey Office of GIS geocoding and address suggestion services.

Purpose

Provides geocoding and address autocomplete functionality by integrating with NJ's ArcGIS REST services while implementing domain port interfaces.

Files

geocoding-client.ts

Implements GeocodingServicePort for single and batch geocoding operations.

Methods:

• geocodeAddress(address) - Geocode single address
• geocodeBatch(addresses) - Geocode multiple addresses in parallel

Features:

• Parallel batch processing with controlled concurrency
• Response validation and transformation
• Error handling with domain-specific exceptions
• Logging for observability

suggestions-client.ts

Implements SuggestionsServicePort for address autocomplete.

Methods:

• getSuggestions(query) - Get address suggestions for partial input

Features:

• Debounce-friendly (quick responses)
• Empty array for short queries (<3 chars)
• Error handling with fallback to empty suggestions

endpoint-builder.ts

Constructs API URLs with query parameters.

Methods:

• buildGeocodeUrl(address, options) - Build geocoding endpoint URL
• buildSuggestUrl(query, options) - Build autocomplete endpoint URL

api-config.ts

API configuration constants and defaults.

Endpoints:

• Geocoding: /findAddressCandidates
• Suggestions: /suggest

Default Parameters:

• outFields: * - Return all fields
• f: json - JSON response format
• maxLocations: 10 - Maximum results

nj-api-types.ts

TypeScript types for NJ API request/response structures.

API Integration

Geocoding Request

GET https://geo.nj.gov/arcgis/rest/services/Tasks/NJ_Geocode/GeocodeServer/findAddressCandidates
  ?SingleLine=123+Main+St,+Newark,+NJ
  &outFields=*
  &f=json

Response Transformation

// NJ API response
{
  candidates: [{
    address: "123 Main St, Newark, NJ 07102",
    location: { x: -74.1724, y: 40.7357 },
    score: 95,
    attributes: { Zone: "Newark", County: "Essex" }
  }]
}

// Transformed to domain entity
{
  inputAddress: "123 Main St",
  formattedAddress: "123 Main St, Newark, NJ 07102",
  municipality: "Newark",
  coordinates: { latitude: 40.7357, longitude: -74.1724 },
  score: 95,
  fromCache: false
}

Error Handling

Adapters transform API errors into domain errors:

// API timeout
throw new ApiTimeoutError({ url, timeoutMs: 10000 });

// Malformed response
throw new InvalidApiResponseError("Response missing candidates array", { url });

// No results found
throw new AddressNotFoundError({ address, score: 0 });

Configuration

Configured via environment variables in lib/config.ts:

NJ_API_BASE_URL=https://geo.nj.gov/arcgis/rest/services/Tasks/NJ_Geocode/GeocodeServer
NJ_API_TIMEOUT_MS=10000
NJ_API_RETRY_ENABLED=true
NJ_API_MAX_RETRIES=3

Testing

• Unit tests: Mocked HTTP client responses
• Integration tests: Real API calls (.integration.test.ts)
• Logging coverage: Verify all code paths log appropriately