Class SuggestService

SuggestService - Address and POI autocomplete using Cercalia Suggest API

This service provides real-time autocomplete suggestions for addresses, streets, cities, and POIs. It's designed for typeahead search experiences.

Key Features

Street suggestions: Autocomplete street names with house number availability
City suggestions: Find cities/localities by partial name
POI suggestions: Search points of interest with category filtering
Geocoding: Convert suggestions to precise coordinates

Usage Examples

const suggest = new SuggestService(config);

// Basic address autocomplete
const results = await suggest.search({ text: 'Provença 5' });

// Filter by country and type
const streets = await suggest.search({ 
  text: 'Gran Via', 
  countryCode: 'ESP',
  geoType: 'st' 
});

// Geocode a specific result
const coords = await suggest.geocode({
  streetCode: results[0].street?.code,
  streetNumber: '589',
  cityCode: results[0].city?.code
});

See

https://docs.cercalia.com/docs/cercalia-webservices/suggest/

Hierarchy (View Summary)

CercaliaClient
- SuggestService

Index

Constructors

constructor

new SuggestService(config: CercaliaConfig): SuggestService
Parameters
- config: CercaliaConfig
Returns SuggestService
Overrides CercaliaClient.constructor
- Defined in services/suggest.service.ts:119

Properties

`Protected`config

config: CercaliaConfig

Configuration for the Cercalia API connection.

Methods

findAndGeocode

findAndGeocode(
text: string,
options?: { countryCode?: string; streetNumber?: string },
): Promise<SuggestGeocodeResult | null>
Combined search and geocode - finds and geocodes the best match

This is a convenience method that combines search and geocode in one call. Useful when you need coordinates directly from a text query.
Parameters
- text: string
  Address text to search
- Optionaloptions: { countryCode?: string; streetNumber?: string }
  Optional filtering options
Returns Promise<SuggestGeocodeResult | null>
Geocoded result of the best match, or null if no results
Example
```
const location = await service.findAndGeocode('Provença 589, Barcelona');
if (location) {
  logger.info(location.coord); // { lat: 41.41, lng: 2.18 }
}
```
- Defined in services/suggest.service.ts:407

geocode

geocode(options: SuggestGeocodeOptions): Promise<SuggestGeocodeResult>
Geocode a suggestion to get precise coordinates

After selecting a suggestion from search(), use this method to get the exact coordinates for the address. For streets, you can specify a house number to get the precise location.
Parameters
- options: SuggestGeocodeOptions
  Geocode options with codes from suggestion
Returns Promise<SuggestGeocodeResult>
Geocoded result with coordinates and full address
Throws
Error if geocoding fails or no results found
Example
```
// First search for suggestions
const suggestions = await service.search({ text: 'Provença 5' });

// Then geocode the selected suggestion with specific number
const location = await service.geocode({
  streetCode: suggestions[0].street?.code,
  streetNumber: '589',
  cityCode: suggestions[0].city?.code,
  countryCode: 'ESP'
});

logger.info(location.coord); // { lat: 41.41, lng: 2.18 }
```
- Defined in services/suggest.service.ts:361

`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

search

search(options: SuggestOptions): Promise<SuggestResult[]>
Search for address/POI suggestions based on partial text input

Use this method for autocomplete/typeahead functionality. Returns suggestions ordered by relevance. Minimum 3 characters recommended for best results.
Parameters
- options: SuggestOptions
  Search configuration
Returns Promise<SuggestResult[]>
Array of suggestions ordered by relevance
Example
```
// Search streets in Barcelona
const results = await service.search({
  text: 'Diagonal',
  countryCode: 'ESP',
  geoType: 'st'
});

// Search POIs near a location
const pois = await service.search({
  text: 'Restaurant',
  geoType: 'poi',
  center: { lat: 41.39, lng: 2.15 },
  radius: 5000
});
```
- Defined in services/suggest.service.ts:197

searchCities

searchCities(text: string, countryCode?: string): Promise<SuggestResult[]>
Search for city/locality suggestions only

Convenience method for city-only autocomplete.
Parameters
- text: string
  Search text
- OptionalcountryCode: string
  Optional country code filter
Returns Promise<SuggestResult[]>
Array of city suggestions
Example
```
const cities = await service.searchCities('Barcel', 'ESP');
```
- Defined in services/suggest.service.ts:294

searchPois

searchPois(
    text: string,
    options?: {
        center?: Coordinate;
        countryCode?: string;
        poiCategories?: string[];
        radius?: number;
    },
): Promise<SuggestResult[]>
Search for POI suggestions only

Convenience method for POI-only autocomplete.
Parameters
- text: string
  Search text
- Optionaloptions: {
      center?: Coordinate;
      countryCode?: string;
      poiCategories?: string[];
      radius?: number;
  }
  Optional filtering options
Returns Promise<SuggestResult[]>
Array of POI suggestions
Example
```
// Search restaurants near Barcelona
const pois = await service.searchPois('Restaurant', {
  center: { lat: 41.39, lng: 2.15 },
  radius: 5000,
  poiCategories: ['C014']
});
```
- Defined in services/suggest.service.ts:321

searchStreets

searchStreets(text: string, countryCode?: string): Promise<SuggestResult[]>
Search for street suggestions only

Convenience method for street-only autocomplete.
Parameters
- text: string
  Search text
- OptionalcountryCode: string
  Optional country code filter
Returns Promise<SuggestResult[]>
Array of street suggestions
Example
```
const streets = await service.searchStreets('Gran Via', 'ESP');
```
- Defined in services/suggest.service.ts:272

Class SuggestService

Key Features

Usage Examples

See

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns SuggestService

Properties

Protectedconfig

Methods

findAndGeocode

Parameters

Returns Promise<SuggestGeocodeResult | null>

Example

geocode

Parameters

Returns Promise<SuggestGeocodeResult>

Throws

Example

Protectedrequest

Type Parameters

Parameters

Returns Promise<T>

Throws

Throws

Example

search

Parameters

Returns Promise<SuggestResult[]>

Example

searchCities

Parameters

Returns Promise<SuggestResult[]>

Example

searchPois

Parameters

Returns Promise<SuggestResult[]>

Example

searchStreets

Parameters

Returns Promise<SuggestResult[]>

Example

Settings

On This Page

`Protected`config

`Protected`request