Package com.cercalia.sdk.model.geocoding

Class GeocodingCandidate

java.lang.Object
com.cercalia.sdk.model.geocoding.GeocodingCandidate
public final class GeocodingCandidate extends Object
Represents a geocoding result candidate from the Cercalia API.

Contains comprehensive location information including:

  • Geographic coordinates (latitude/longitude)
  • Full address components (street, locality, municipality, etc.)
  • Administrative hierarchy (district, subregion, region, country)
  • Administrative IDs for each level (maintaining data integrity)
  • Result type and precision level

All administrative fields are mapped directly from the API response without fallbacks, ensuring data transparency and allowing consumers to handle missing information appropriately. 


 GeocodingService service = new GeocodingService(config);
 List<GeocodingCandidate> results = service.geocode(GeocodingOptions.builder()
     .street("Carrer de la Provença")
     .locality("Barcelona")
     .countryCode("ESP")
     .build());

 for (GeocodingCandidate candidate : results) {
     System.out.println(candidate.getName() + ": " + candidate.getCoord());
 }

  • Method Details

    • builder

      public static GeocodingCandidate.Builder builder()
      Creates a new builder for constructing GeocodingCandidate instances.

      Provides a fluent API for setting all optional fields before building the final object.

      Returns:
      a new Builder instance

    • getId

      @NotNull public @NotNull String getId()
      Returns the unique identifier for this location.

      The ID format varies depending on the location type and data source. Common formats include numeric IDs (e.g., "28"), country codes (e.g., "ESP"), or composite identifiers (e.g., "ESPMAD").

      Returns:
      the location identifier, never null

    • getName

      @NotNull public @NotNull String getName()
      Returns the display name of this location.

      This is typically the most recognizable name for the location, which may be a street name, city name, POI name, or country name depending on the result type.

      Returns:
      the location name, never null

    • getLabel

      @Nullable public @Nullable String getLabel()
      Returns the full address label or description.

      This is the formatted address string as returned by the Cercalia API. May include the full street address, postal code, and locality.

      Returns:
      the address label, or null if not available

    • getStreet

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

      Available for street-level and address-level results.

      Returns:
      the street name, or null if not applicable

    • getStreetCode

      @Nullable public @Nullable String getStreetCode()
      Returns the street code/identifier.

      The internal identifier for the street in the Cercalia database.

      Returns:
      the street code, or null if not available

    • getLocality

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

      This is the primary city or locality for the location. Mapped directly from the API without administrative fallbacks.

      Returns:
      the locality name, or null if not available

    • getLocalityCode

      @Nullable public @Nullable String getLocalityCode()
      Returns the locality (locality) code/identifier.

      The internal identifier for the locality in the Cercalia database. Format varies but may include numeric or alphanumeric codes.

      Returns:
      the locality code, or null if not available

    • getMunicipality

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

      This is the administrative municipality for the location. Mapped directly from the API without administrative fallbacks.

      Returns:
      the municipality name, or null if not available

    • getMunicipalityCode

      @Nullable public @Nullable String getMunicipalityCode()
      Returns the municipality code/identifier.

      The internal identifier for the municipality in the Cercalia database. Note: This field name maintains a deliberate typo ("municipalityCode") for 1:1 compatibility with the TypeScript SDK.

      Returns:
      the municipality code, or null if not available

    • getDistrict

      @Nullable public @Nullable String getDistrict()
      Returns the district name.

      This is an administrative subdivision within the municipality. Not all locations have district information.

      Returns:
      the district name, or null if not available

    • getDistrictCode

      @Nullable public @Nullable String getDistrictCode()
      Returns the district code/identifier.

      The internal identifier for the district in the Cercalia database.

      Returns:
      the district code, or null if not available

    • getSubregion

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

      This is the administrative subregion (typically province) for the location. Mapped directly from the API without administrative fallbacks.

      Returns:
      the subregion name, or null if not available

    • getSubregionCode

      @Nullable public @Nullable String getSubregionCode()
      Returns the subregion (subregion) code/identifier.

      The internal identifier for the subregion in the Cercalia database.

      Returns:
      the subregion code, or null if not available

    • getRegion

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

      This is the administrative region for the location. Mapped directly from the API without administrative fallbacks.

      Returns:
      the region name, or null if not available

    • getRegionCode

      @Nullable public @Nullable String getRegionCode()
      Returns the region (state/autonomous community) code/identifier.

      The internal identifier for the region in the Cercalia database.

      Returns:
      the region code, or null if not available

    • getCountry

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

      This is the country name in the language specified in the API request.

      Returns:
      the country name, or null if not available

    • getCountryCode

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

      Common formats include "ESP" (3-letter) or "ES" (2-letter). The exact format depends on the Cercalia API response.

      Returns:
      the country code, or null if not available

    • getPostalCode

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

      The postal code format varies by country (e.g., "08013" for Spain). May be null for some location types like countries or regions.

      Returns:
      the postal code, or null if not available

    • getHouseNumber

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

      Available only for address-level results that include specific building numbers.

      Returns:
      the house number, or null if not available

    • getCoord

      @NotNull public @NotNull Coordinate getCoord()
      Returns the geographic coordinates of this location.

      Coordinates are always present for valid geocoding results. No default values (like 0.0, 0.0) are used to avoid incorrect data.

      Returns:
      the coordinate with latitude and longitude, never null

    • getType

      @NotNull public @NotNull GeocodingCandidateType getType()
      Returns the type of this geocoding result.

      Indicates whether this result is an address, street, POI, locality, etc. Useful for filtering and display purposes.

      Returns:
      the result type, never null
      See Also:

    • getLevel

      @Nullable public @Nullable GeocodingLevel getLevel()
      Returns the precision level of this geocoding result.

      Indicates the administrative level or precision of the result. Higher precision results (e.g., ADR, ST) have more specific location information.

      Returns:
      the geocoding level, or null if not available
      See Also:

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object