Package com.cercalia.sdk.services

Class SuggestService

java.lang.Object
com.cercalia.sdk.CercaliaClient
com.cercalia.sdk.services.SuggestService
public class SuggestService extends CercaliaClient
Service for 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

 SuggestService service = new SuggestService(config);
 
 // 1. Basic address autocomplete
 List<SuggestResult> results = service.search(SuggestOptions.builder()
     .text("Provença 5")
     .build());
 
 // 2. Filter by country and type
 List<SuggestResult> streets = service.search(SuggestOptions.builder()
     .text("Gran Via")
     .countryCode("ESP")
     .geoType(SuggestGeoType.STREET)
     .build());
 
 // 3. Geocode a specific result to get coordinates
 if (!results.isEmpty()) {
     SuggestResult best = results.get(0);
     SuggestGeocodeResult coords = service.geocode(SuggestGeocodeOptions.builder()
         .cityCode(best.getCity().getCode())
         .streetCode(best.getStreet().getCode())
         .streetNumber("5")
         .build());
 }
See Also:

  • Constructor Details

    • SuggestService

      public SuggestService(@NotNull @NotNull CercaliaConfig config)
      Creates a new SuggestService with the specified configuration.
      Parameters:
      config - the Cercalia configuration

  • Method Details

    • search

      @NotNull public @NotNull List<SuggestResult> search(@NotNull @NotNull SuggestOptions options)
      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 - search configuration
      Returns:
      list of suggestions ordered by relevance
      Throws:
      CercaliaException - if the request fails

    • searchAsync

      @NotNull public @NotNull CompletableFuture<List<SuggestResult>> searchAsync(@NotNull @NotNull SuggestOptions options)
      Search for address/POI suggestions asynchronously.
      Parameters:
      options - search configuration
      Returns:
      a CompletableFuture with the list of suggestions

    • searchStreets

      @NotNull public @NotNull List<SuggestResult> searchStreets(@NotNull @NotNull String text, @Nullable @Nullable String countryCode)
      Search for street suggestions only.

      Convenience method for street-only autocomplete.

      Parameters:
      text - search text
      countryCode - optional country code filter
      Returns:
      list of street suggestions
      Throws:
      CercaliaException - if the request fails

    • searchStreetsAsync

      @NotNull public @NotNull CompletableFuture<List<SuggestResult>> searchStreetsAsync(@NotNull @NotNull String text, @Nullable @Nullable String countryCode)
      Search for street suggestions asynchronously.
      Parameters:
      text - search text
      countryCode - optional country code filter
      Returns:
      a CompletableFuture with the list of street suggestions

    • searchCities

      @NotNull public @NotNull List<SuggestResult> searchCities(@NotNull @NotNull String text, @Nullable @Nullable String countryCode)
      Search for city/locality suggestions only.

      Convenience method for city-only autocomplete.

      Parameters:
      text - search text
      countryCode - optional country code filter
      Returns:
      list of city suggestions
      Throws:
      CercaliaException - if the request fails

    • searchCitiesAsync

      @NotNull public @NotNull CompletableFuture<List<SuggestResult>> searchCitiesAsync(@NotNull @NotNull String text, @Nullable @Nullable String countryCode)
      Search for city/locality suggestions asynchronously.
      Parameters:
      text - search text
      countryCode - optional country code filter
      Returns:
      a CompletableFuture with the list of city suggestions

    • searchPois

      @NotNull public @NotNull List<SuggestResult> searchPois(@NotNull @NotNull String text, @Nullable @Nullable String countryCode, @Nullable @Nullable Coordinate center, @Nullable @Nullable Integer radius, @Nullable @Nullable List<String> poiCategories)
      Search for POI suggestions only.

      Convenience method for POI-only autocomplete.

      Parameters:
      text - search text
      countryCode - optional country code filter
      center - optional center point for proximity search
      radius - optional radius in meters
      poiCategories - optional POI category codes
      Returns:
      list of POI suggestions
      Throws:
      CercaliaException - if the request fails

    • searchPoisAsync

      @NotNull public @NotNull CompletableFuture<List<SuggestResult>> searchPoisAsync(@NotNull @NotNull String text, @Nullable @Nullable String countryCode, @Nullable @Nullable Coordinate center, @Nullable @Nullable Integer radius, @Nullable @Nullable List<String> poiCategories)
      Search for POI suggestions asynchronously.
      Parameters:
      text - search text
      countryCode - optional country code filter
      center - optional center point for proximity search
      radius - optional radius in meters
      poiCategories - optional POI category codes
      Returns:
      a CompletableFuture with the list of POI suggestions

    • geocode

      @NotNull public @NotNull SuggestGeocodeResult geocode(@NotNull @NotNull SuggestGeocodeOptions options)
      Geocode a suggestion to get precise coordinates.

      After selecting a suggestion from search(SuggestOptions), 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 - geocode options with codes from suggestion
      Returns:
      geocoded result with coordinates and full address
      Throws:
      CercaliaException - if geocoding fails or no results found

    • geocodeAsync

      @NotNull public @NotNull CompletableFuture<SuggestGeocodeResult> geocodeAsync(@NotNull @NotNull SuggestGeocodeOptions options)
      Geocode a suggestion asynchronously.
      Parameters:
      options - geocode options with codes from suggestion
      Returns:
      a CompletableFuture with the geocoded result

    • findAndGeocode

      @Nullable public @Nullable SuggestGeocodeResult findAndGeocode(@NotNull @NotNull String text, @Nullable @Nullable String countryCode, @Nullable @Nullable String streetNumber)
      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 - address text to search
      countryCode - optional country code filter
      streetNumber - optional street number for geocoding
      Returns:
      geocoded result of the best match, or null if no results
      Throws:
      CercaliaException - if the request fails

    • findAndGeocodeAsync

      @NotNull public @NotNull CompletableFuture<SuggestGeocodeResult> findAndGeocodeAsync(@NotNull @NotNull String text, @Nullable @Nullable String countryCode, @Nullable @Nullable String streetNumber)
      Combined search and geocode asynchronously.
      Parameters:
      text - address text to search
      countryCode - optional country code filter
      streetNumber - optional street number for geocoding
      Returns:
      a CompletableFuture with the geocoded result, or null if no results