Server SDKs

TypeScript client reference

Constructor options, request types, responses, and errors.

Import public classes and types from @affordable-geo-apis/sdk.

GeocodingClient

new GeocodingClient(options: ClientOptions)
client.geocode(request: AddressRequest, options?: RequestOptions): Promise<GeocodingResponse>
client.search(request: SearchRequest, options?: RequestOptions): Promise<GeocodingResponse>
client.reverseGeocode(request: ReverseRequest, options?: RequestOptions): Promise<GeocodingResponse>
client.autocomplete(request: AutocompleteRequest, options?: RequestOptions): Promise<AutocompleteResponse>
client.resolveAutocomplete(suggestion: AutocompleteSuggestion, options?: RequestOptions): Promise<GeocodingResult>

ClientOptions

Option	Type	Default / requirement
baseUrl	string	Required origin/prefix; HTTPS except loopback HTTP
apiKey	string	Required nonempty primary key
confidenceThreshold	number	0.8; finite value in [0, 1]
fallbacks	readonly FallbackOptions[]	[]; used in configured order
fallbackOn	readonly FallbackTrigger[]	All five default triggers
fallbackBudget	{ maxRequests: number }	Unlimited if absent; nonnegative safe integer
fallbackCircuitBreaker	FallbackCircuitBreakerOptions	Disabled if absent
timeoutMs	number	10000; positive integer at most 2147483647
fetch	typeof globalThis.fetch	Native fetch; must honor cancellation

FallbackOptions has provider: 'google' | 'here' and apiKey: string. FallbackCircuitBreakerOptions has positive safe integers failureThreshold and cooldownMs. Invalid options throw before making requests.

RequestOptions

{ signal?: AbortSignal } controls caller cancellation and optional total deadlines. Omit it to apply only per-provider deadlines.

Requests

interface AddressRequest {
  street: string; // house number and street
  city?: string;
  state?: string;
  zip?: string;
  country?: string;
  exclude_sources?: string[];
}

interface ReverseRequest {
  lat: number;
  lon: number;
  country?: string;
  exclude_sources?: string[];
}

interface Point { lat: number; lon: number }

interface SearchRequest {
  q: string; // 1–256 characters
  country?: string;
  near?: Point;
  limit?: number; // 1–40, default 10
  exclude_sources?: string[];
}

Primary geocode requests require at least one of city/state/ZIP. For geocode and reverse, country is an SDK routing hint and is not sent to the API; search also sends it as a filter. Invalid search q, limit, or near rejects with TypeError before any request. The API validates primary request fields; see geocode, search, reverse, and source exclusions.

Results and responses

type Provider = 'primary' | 'google' | 'here';
type FallbackTrigger = 'no_results' | 'low_confidence' | 'timeout' | 'network' | 'server_error';
type FallbackReason = FallbackTrigger | 'unsupported_country';

type ResultType = 'address' | 'venue' | 'street' | 'zip' | 'neighborhood' | 'borough' | 'city' | 'county' | 'state' | 'country' | '';

interface GeocodingResult {
  id: string;
  label: string;
  type: ResultType;
  houseNumber: string;
  street: string; // street name only
  city: string;
  state: string;
  zip: string;
  country: string;
  lat: number;
  lon: number;
  confidence: number;
  matchType: string; // primary only: 'exact' | 'interpolated' | 'fallback'
  source: string;
  provider: Provider;
}

interface GeocodingResponse {
  results: GeocodingResult[];
  provider: Provider;
  providerResponse?: Record<string, unknown>;
  fallbackReason: FallbackReason | null;
  attempts: Attempt[];
}

interface Attempt {
  provider: Provider;
  outcome: 'matched' | 'no_results' | 'low_confidence' | 'error' | 'skipped';
  skipReason?: 'budget_exhausted' | 'circuit_open' | 'unsupported_country';
  error?: GeocodingError;
}

Missing text fields are empty strings. Result country is recognized ISO alpha-2 or an empty string. Confidence is numeric in [0, 1], with 0 for unavailable values. Raw selected backup bodies are preserved; providerResponse is absent for primary. See result semantics.

Autocomplete types

AutocompleteRequest requires q (1–256 nonblank characters) and a recognized country. It accepts optional near (Point), limit (1–10, default 5), exclude_sources, and sessionToken. sessionToken groups Google Places requests across keystrokes; the client generates one when omitted.

AutocompleteResponse contains suggestions, provider, fallbackReason, and attempts, plus providerResponse when a backup wins. Each AutocompleteSuggestion has id, label, and provider, with sessionToken for Google. Pass the suggestion unchanged to resolveAutocomplete; it returns a GeocodingResult with address fields and coordinates. Both methods accept RequestOptions.signal. See address autocomplete.

Selection resolution

Resolution returns the address directly, without an envelope, attempt history, or raw provider response. It calls only the suggestion's provider and bypasses fallback budgets/circuit breakers. An empty primary lookup throws GeocodingError with code provider_error. Google/HERE must be configured on the resolving server client. Primary resolution calls GET /v1/place?id=. sessionToken remains SDK-only.

GeocodingError

Extends Error, with name: 'GeocodingError', message, readonly provider, readonly code, optional readonly status, and readonly attempts.

code is http, network, timeout, invalid_response, provider_error, or unsupported_country. Terminal failures include the provider-chain history. Caller aborts propagate separately. There is no toJSON() method; explicitly select properties for structured logs.