Class ReverseGeocodingService

Service for reverse geocoding operations using Cercalia API.

Remarks

Converts geographic coordinates into address information and administrative hierarchy. Also supports timezone lookup and special category queries.

Hierarchy (View Summary)

CercaliaClient
- ReverseGeocodingService

Index

Constructors

Properties

Methods

getIntersectingRegions getTimezone request reverseGeocode reverseGeocodeBatch

Constructors

constructor

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

Properties

`Protected`config

config: CercaliaConfig

Configuration for the Cercalia API connection.

Methods

getIntersectingRegions

getIntersectingRegions(
wkt: string,
level?: "ct" | "mun" | "subreg" | "reg",
): Promise<ReverseGeocodeResult[]>
Gets regions/municipalities that intersect a polygon.
Parameters
- wkt: string
  Polygon geometry in WKT format.
- level: "ct" | "mun" | "subreg" | "reg" = 'mun'
  Administrative level to return ('ct', 'mun', 'subreg', 'reg').
Returns Promise<ReverseGeocodeResult[]>
Promise resolving to array of administrative regions in the polygon.
Example
```
const polygon = 'POLYGON((2.0 41.0, 2.5 41.0, 2.5 41.5, 2.0 41.5, 2.0 41.0))';
const municipalities = await service.getIntersectingRegions(polygon, 'mun');
```
- Defined in services/reversegeocoding.service.ts:162

getTimezone

getTimezone(
coord: Coordinate,
options?: TimezoneOptions,
): Promise<TimezoneResult | null>
Gets timezone information for a coordinate.
Parameters
- coord: Coordinate
  The coordinate to get timezone for.
- options: TimezoneOptions = {}
  Optional datetime in ISO 8601 format.
Returns Promise<TimezoneResult | null>
Promise resolving to timezone information or null if not found.
Example
```
const tz = await service.getTimezone(
  { lat: 41.3851, lng: 2.1734 },
  { dateTime: '2024-01-15T14:30:00Z' }
);

if (tz) {
  logger.info(tz.id); // e.g., "Europe/Madrid"
  logger.info(tz.utcOffset); // e.g., 3600
}
```
- Defined in services/reversegeocoding.service.ts:204

`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

reverseGeocode

reverseGeocode(
coord: Coordinate,
options?: ReverseGeocodeOptions,
): Promise<ReverseGeocodeResult | null>
Reverse geocodes a single coordinate to get address information.
Parameters
- coord: Coordinate
  The coordinate to reverse geocode.
- options: ReverseGeocodeOptions = {}
  Optional reverse geocoding parameters.
Returns Promise<ReverseGeocodeResult | null>
Promise resolving to reverse geocoding result or null if no match.
Example
```
const service = new ReverseGeocodingService(config);
const result = await service.reverseGeocode(
  { lat: 41.3851, lng: 2.1734 }
);

if (result) {
  logger.info(result.ge.street); // e.g., "Carrer de Provença"
  logger.info(result.ge.municipality); // e.g., "Barcelona"
}
```
- Defined in services/reversegeocoding.service.ts:52

reverseGeocodeBatch

reverseGeocodeBatch(
coords: Coordinate[],
options?: ReverseGeocodeOptions,
): Promise<ReverseGeocodeResult[]>
Reverse geocodes multiple coordinates in a single request.
Parameters
- coords: Coordinate[]
  Array of coordinates to reverse geocode (max 100).
- options: ReverseGeocodeOptions = {}
  Optional reverse geocoding parameters.
Returns Promise<ReverseGeocodeResult[]>
Promise resolving to array of reverse geocoding results.
Throws
Error if more than 100 coordinates are provided.
Example
```
const results = await service.reverseGeocodeBatch([
  { lat: 41.3851, lng: 2.1734 },
  { lat: 40.4168, lng: -3.7038 }
]);
```
- Defined in services/reversegeocoding.service.ts:74