Package com.cercalia.sdk.model.geocoding

Class GeocodingOptions

java.lang.Object
com.cercalia.sdk.model.geocoding.GeocodingOptions
public final class GeocodingOptions extends Object
Options for geocoding requests to Cercalia API.

Provides a fluent builder interface for constructing geocoding queries. Supports structured search by address components or free-form text queries. 


 GeocodingService service = new GeocodingService(config);

 // Structured search by address components
 List<GeocodingCandidate> results = service.geocode(GeocodingOptions.builder()
     .street("Carrer de la Provença")
     .locality("Barcelona")
     .postalCode("08013")
     .countryCode("ESP")
     .limit(10)
     .build());

 // Free-form text search
 List<GeocodingCandidate> results = service.geocode(GeocodingOptions.builder()
     .query("Provença 5, Barcelona")
     .fullSearch(true)
     .build());

  • Method Details

    • builder

      public static GeocodingOptions.Builder builder()
      Creates a new builder for constructing GeocodingOptions instances.
      Returns:
      a new Builder instance

    • getQuery

      @Nullable public @Nullable String getQuery()
      Returns the free-form text query for geocoding.

      When set, this takes precedence over structured address components. Use this for general text searches like "Provença 5, Barcelona".

      Returns:
      the text query, or null if using structured search

    • getCountry

      @Nullable public @Nullable String getCountry()
      Returns the country name.

      The full country name (e.g., "Spain", "España").

      Returns:
      the country name, or null if not specified

    • getCountryCode

      @Nullable public @Nullable String getCountryCode()
      Returns the country code (ISO 3166-1).

      Recommended to use 2-letter codes (e.g., "ES" for Spain) or 3-letter codes (e.g., "ESP"). Default is "ESP" if not specified.

      Returns:
      the country code, or null if not specified

    • getLocality

      @Nullable public @Nullable String getLocality()
      Returns the locality (locality) name.

      The primary locality for the search.

      Returns:
      the locality name, or null if not specified

    • getMunicipality

      @Nullable public @Nullable String getMunicipality()
      Returns the municipality name.

      The administrative municipality for the search.

      Returns:
      the municipality name, or null if not specified

    • getRegion

      @Nullable public @Nullable String getRegion()
      Returns the region (state/autonomous community) name.

      The administrative region for the search.

      Returns:
      the region name, or null if not specified

    • getSubregion

      @Nullable public @Nullable String getSubregion()
      Returns the subregion (subregion) name.

      The administrative subregion (typically province) for the search.

      Returns:
      the subregion name, or null if not specified

    • getStreet

      @Nullable public @Nullable String getStreet()
      Returns the street name.

      The street name for structured address search.

      Returns:
      the street name, or null if not specified

    • getPostalCode

      @Nullable public @Nullable String getPostalCode()
      Returns the postal code.

      The postal code for the search area.

      Returns:
      the postal code, or null if not specified

    • getHouseNumber

      @Nullable public @Nullable String getHouseNumber()
      Returns the house number.

      The specific house or building number for the address.

      Returns:
      the house number, or null if not specified

    • getLimit

      @Nullable public @Nullable Integer getLimit()
      Returns the maximum number of results to return.

      Limits the number of candidates returned by the API. If not specified, the API's default limit is used.

      Returns:
      the result limit, or null for API default

    • getFullSearch

      @Nullable public @Nullable Boolean getFullSearch()
      Returns whether to enable full search mode.

      When enabled, performs a more exhaustive search that may include partial matches and broader results. Useful when the initial search returns few or no results.

      Returns:
      true if full search is enabled, false or null otherwise