Package com.cercalia.sdk.services

Class GeocodingService

java.lang.Object
com.cercalia.sdk.CercaliaClient
com.cercalia.sdk.services.GeocodingService
public class GeocodingService extends CercaliaClient
Service for geocoding addresses using the Cercalia API. Converts addresses and place names into geographic coordinates. 

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

 // 2. Road kilometer mark search
 List<GeocodingCandidate> roadResults = service.geocodeRoad("A-2", 582, null);

 // 3. Cities by postal code
 List<PostalCodeCity> cities = service.geocodeCitiesByPostalCode("08013");
See Also:

  • Constructor Details

    • GeocodingService

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

  • Method Details

    • geocode

      @NotNull public @NotNull List<GeocodingCandidate> geocode(@NotNull @NotNull GeocodingOptions options)
      Geocode an address using Cercalia API.
      Parameters:
      options - the geocoding options
      Returns:
      list of geocoding candidates
      Throws:
      CercaliaException - if the request fails

    • geocodeAsync

      @NotNull public @NotNull CompletableFuture<List<GeocodingCandidate>> geocodeAsync(@NotNull @NotNull GeocodingOptions options)
      Geocode an address asynchronously.
      Parameters:
      options - the geocoding options
      Returns:
      a CompletableFuture with the list of geocoding candidates

    • geocodeRoad

      @NotNull public @NotNull List<GeocodingCandidate> geocodeRoad(@NotNull @NotNull String rdn, double km, @Nullable @Nullable GeocodingOptions options)
      Geocode a road milestone (PK).
      Parameters:
      rdn - the road name/identifier
      km - the kilometer mark
      options - additional options (optional)
      Returns:
      list of geocoding candidates
      Throws:
      CercaliaException - if the request fails

    • geocodeRoadAsync

      @NotNull public @NotNull CompletableFuture<List<GeocodingCandidate>> geocodeRoadAsync(@NotNull @NotNull String rdn, double km, @Nullable @Nullable GeocodingOptions options)
      Geocode a road milestone asynchronously.
      Parameters:
      rdn - the road name/identifier
      km - the kilometer mark
      options - additional options (optional)
      Returns:
      a CompletableFuture with the list of geocoding candidates

    • geocodeCitiesByPostalCode

      @NotNull public @NotNull List<PostalCodeCity> geocodeCitiesByPostalCode(@NotNull @NotNull String postalCode, @Nullable @Nullable String countryCode)
      Get list of cities related to a postal code.
      Parameters:
      postalCode - the postal code
      countryCode - the country code (default: ESP)
      Returns:
      list of cities for the postal code
      Throws:
      CercaliaException - if the request fails

    • geocodeCitiesByPostalCode

      @NotNull public @NotNull List<PostalCodeCity> geocodeCitiesByPostalCode(@NotNull @NotNull String postalCode)
      Get list of cities related to a postal code (default country: ESP).
      Parameters:
      postalCode - the postal code
      Returns:
      list of cities for the postal code
      Throws:
      CercaliaException - if the request fails

    • geocodeCitiesByPostalCodeAsync

      @NotNull public @NotNull CompletableFuture<List<PostalCodeCity>> geocodeCitiesByPostalCodeAsync(@NotNull @NotNull String postalCode, @Nullable @Nullable String countryCode)
      Get list of cities related to a postal code asynchronously.
      Parameters:
      postalCode - the postal code
      countryCode - the country code (default: ESP)
      Returns:
      a CompletableFuture with the list of cities