Package com.cercalia.sdk.services

Class ReverseGeocodingService

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

 ReverseGeocodingService service = new ReverseGeocodingService(config);
 Coordinate coord = new Coordinate(41.3851, 2.1734);
 
 // 1. Reverse geocode a single coordinate to an address
 ReverseGeocodeResult result = service.reverseGeocode(coord);
 if (result != null) {
     System.out.println(result.getGe().getLabel());
 }

 // 2. Batch reverse geocoding (max 100)
 List<Coordinate> coords = Arrays.asList(coord, new Coordinate(40.4168, -3.7038));
 List<ReverseGeocodeResult> batchResults = service.reverseGeocodeBatch(coords);

 // 3. Get timezone for a coordinate
 TimezoneResult tz = service.getTimezone(coord);
 System.out.println("Timezone: " + tz.getName() + " (Offset: " + tz.getUtcOffset() + "s)");
See Also:

  • Constructor Details

    • ReverseGeocodingService

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

  • Method Details

    • reverseGeocode

      @Nullable public @Nullable ReverseGeocodeResult reverseGeocode(@NotNull @NotNull Coordinate coord)
      Reverse geocode a coordinate to get address information.
      Parameters:
      coord - the coordinate to reverse geocode
      Returns:
      the reverse geocode result, or null if not found
      Throws:
      CercaliaException - if the request fails

    • reverseGeocode

      @Nullable public @Nullable ReverseGeocodeResult reverseGeocode(@NotNull @NotNull Coordinate coord, @Nullable @Nullable ReverseGeocodeOptions options)
      Reverse geocode a coordinate to get address information.
      Parameters:
      coord - the coordinate to reverse geocode
      options - the reverse geocoding options
      Returns:
      the reverse geocode result, or null if not found
      Throws:
      CercaliaException - if the request fails

    • reverseGeocodeAsync

      @NotNull public @NotNull CompletableFuture<ReverseGeocodeResult> reverseGeocodeAsync(@NotNull @NotNull Coordinate coord)
      Reverse geocode a coordinate asynchronously.
      Parameters:
      coord - the coordinate to reverse geocode
      Returns:
      a CompletableFuture with the result

    • reverseGeocodeAsync

      @NotNull public @NotNull CompletableFuture<ReverseGeocodeResult> reverseGeocodeAsync(@NotNull @NotNull Coordinate coord, @Nullable @Nullable ReverseGeocodeOptions options)
      Reverse geocode a coordinate asynchronously.
      Parameters:
      coord - the coordinate to reverse geocode
      options - the reverse geocoding options
      Returns:
      a CompletableFuture with the result

    • reverseGeocodeBatch

      @NotNull public @NotNull List<ReverseGeocodeResult> reverseGeocodeBatch(@NotNull @NotNull List<Coordinate> coords)
      Reverse geocode multiple coordinates in a single request (max 100).
      Parameters:
      coords - the coordinates to reverse geocode
      Returns:
      list of reverse geocode results
      Throws:
      CercaliaException - if the request fails
      IllegalArgumentException - if more than 100 coordinates are provided

    • reverseGeocodeBatch

      @NotNull public @NotNull List<ReverseGeocodeResult> reverseGeocodeBatch(@NotNull @NotNull List<Coordinate> coords, @Nullable @Nullable ReverseGeocodeOptions options)
      Reverse geocode multiple coordinates in a single request (max 100).
      Parameters:
      coords - the coordinates to reverse geocode
      options - the reverse geocoding options
      Returns:
      list of reverse geocode results
      Throws:
      CercaliaException - if the request fails
      IllegalArgumentException - if more than 100 coordinates are provided

    • reverseGeocodeBatchAsync

      @NotNull public @NotNull CompletableFuture<List<ReverseGeocodeResult>> reverseGeocodeBatchAsync(@NotNull @NotNull List<Coordinate> coords, @Nullable @Nullable ReverseGeocodeOptions options)
      Reverse geocode multiple coordinates asynchronously.
      Parameters:
      coords - the coordinates to reverse geocode
      options - the reverse geocoding options
      Returns:
      a CompletableFuture with the results

    • getIntersectingRegions

      @NotNull public @NotNull List<ReverseGeocodeResult> getIntersectingRegions(@NotNull @NotNull String wkt, @NotNull @NotNull String level)
      Get regions/municipalities intersecting a polygon (WKT).
      Parameters:
      wkt - the WKT polygon
      level - the geographic level (ct, mun, subreg, reg)
      Returns:
      list of intersecting regions
      Throws:
      CercaliaException - if the request fails

    • getIntersectingRegionsAsync

      @NotNull public @NotNull CompletableFuture<List<ReverseGeocodeResult>> getIntersectingRegionsAsync(@NotNull @NotNull String wkt, @NotNull @NotNull String level)
      Get regions/municipalities intersecting a polygon asynchronously.
      Parameters:
      wkt - the WKT polygon
      level - the geographic level (ct, mun, subreg, reg)
      Returns:
      a CompletableFuture with the results

    • getTimezone

      @Nullable public @Nullable TimezoneResult getTimezone(@NotNull @NotNull Coordinate coord)
      Get timezone information for a coordinate.
      Parameters:
      coord - the coordinate to get timezone for
      Returns:
      timezone information, or null if not found
      Throws:
      CercaliaException - if the request fails

    • getTimezone

      @Nullable public @Nullable TimezoneResult getTimezone(@NotNull @NotNull Coordinate coord, @Nullable @Nullable TimezoneOptions options)
      Get timezone information for a coordinate.
      Parameters:
      coord - the coordinate to get timezone for
      options - optional datetime in ISO 8601 format
      Returns:
      timezone information, or null if not found
      Throws:
      CercaliaException - if the request fails

    • getTimezoneAsync

      @NotNull public @NotNull CompletableFuture<TimezoneResult> getTimezoneAsync(@NotNull @NotNull Coordinate coord, @Nullable @Nullable TimezoneOptions options)
      Get timezone information for a coordinate asynchronously.
      Parameters:
      coord - the coordinate to get timezone for
      options - optional datetime in ISO 8601 format
      Returns:
      a CompletableFuture with the result