Class GeocodingService

Service for geocoding operations using the Cercalia API.

Remarks

This service implements direct mapping from Cercalia XML/JSON responses following the SDK's Golden Rules:

No administrative fallbacks (city will be null if API returns null)
All IDs are extracted alongside their names
Coordinates use non-null assertions after validation

Hierarchy (View Summary)

CercaliaClient
- GeocodingService

Index

Constructors

Properties

Methods

geocode geocodeCitiesByPostalCode geocodeRoad request

Constructors

constructor

new GeocodingService(config: CercaliaConfig): GeocodingService
Creates a new GeocodingService instance.
Parameters
- config: CercaliaConfig
  The Cercalia API configuration.
Returns GeocodingService
Overrides CercaliaClient.constructor
- Defined in services/geocoding.service.ts:86

Properties

`Protected`config

config: CercaliaConfig

Configuration for the Cercalia API connection.

Methods

geocode

geocode(options: GeocodingOptions): Promise<GeocodingCandidate[]>
Geocodes an address using Cercalia's structured search mode.
Parameters
- options: GeocodingOptions
  Search parameters including locality, municipality, street, etc.
Returns Promise<GeocodingCandidate[]>
Promise resolving to an array of geocoding candidates.
Throws
When API returns a non-recoverable error (not 30006).
Remarks
- Uses cmd=cand with mode=0 for structured search.
- Error code 30006 ("No candidates found") returns an empty array.
- Default country code is 'ESP' if not specified.
Example
```
const service = new GeocodingService({ apiKey: '...' });
const results = await service.geocode({
  locality: 'Madrid',
  street: 'Gran Via',
  houseNumber: '1'
});
```
- Defined in services/geocoding.service.ts:113

geocodeCitiesByPostalCode

geocodeCitiesByPostalCode(
postalCode: string,
countryCode?: string,
): Promise<PostalCodeCity[]>
Retrieves cities associated with a postal code.
Parameters
- postalCode: string
  The postal code to search for.
- countryCode: string = 'ESP'
  ISO country code (default: 'ESP').
Returns Promise<PostalCodeCity[]>
Promise resolving to an array of cities matching the postal code.
Throws
When API returns an error.
Example
```
const cities = await service.geocodeCitiesByPostalCode('28013', 'ESP');
```
- Defined in services/geocoding.service.ts:319

geocodeRoad

geocodeRoad(
    rdn: string,
    km: number,
    options?: GeocodingOptions,
): Promise<GeocodingCandidate[]>
Geocodes a road milestone (PK) using Cercalia's road search.
Parameters
- rdn: string
  Road designation (e.g., 'A-1', 'N-II').
- km: number
  Kilometer point on the road.
- Optionaloptions: GeocodingOptions
  Optional search parameters (countryCode, municipality, etc.).
Returns Promise<GeocodingCandidate[]>
Promise resolving to an array of geocoding candidates.
Throws
When API returns a non-recoverable error.
Example
```
const results = await service.geocodeRoad('A-1', 50, {
  countryCode: 'ESP'
});
```
- Defined in services/geocoding.service.ts:249

`Protected`request

request<T>(
    params: Record<string, string>,
    operationName?: string,
    baseUrl?: string,
): Promise<T>
Executes a generic request to the Cercalia API.
Type Parameters
- T
Parameters
- params: Record<string, string>
  Query parameters for the API request.
- operationName: string = 'Cercalia Request'
  Human-readable name for logging and debugging.
- OptionalbaseUrl: string
  Optional override for the base API URL.
Returns Promise<T>
A promise resolving to the parsed API response.
Throws
Error with code '30006' when no results are found.

Throws
Error for HTTP errors or invalid JSON responses.
Example
```
const response = await this.request<MyResponse>(
  { cmd: 'cand', adr: 'Gran Via 1' },
  'Geocoding'
);
```
Inherited from CercaliaClient.request
- Defined in services/cercalia-client.ts:68