Package com.cercalia.sdk.services

Class PoiService

java.lang.Object
com.cercalia.sdk.CercaliaClient
com.cercalia.sdk.services.PoiService
public class PoiService extends CercaliaClient
Service for searching Points of Interest (POI) using the Cercalia API.

Supports multiple search modes:

  • Nearest POIs by straight-line distance (cmd=prox)
  • Nearest POIs with routing (cmd=prox with weight)
  • POIs along a route (cmd=geom)
  • POIs inside a map extent (cmd=map)
  • POIs inside a polygon (cmd=prox with wkt)
  • Weather forecast (cmd=prox with D00M05 category)

 PoiService service = new PoiService(config);
 
 // 1. Search POIs inside a polygon (WKT)
 List<Poi> pois = service.searchInPolygon(PoiInPolygonOptions.builder()
     .wkt("POLYGON((2.17 41.38, 2.18 41.38, 2.18 41.39, 2.17 41.39, 2.17 41.38))")
     .categories("D00GASP")
     .build());

 // 2. Search POIs along a route
 List<Poi> routePois = service.searchAlongRoute(PoiAlongRouteOptions.builder()
     .routeId("ROUTE_ID_FROM_ROUTING_SERVICE")
     .categories("D00GASP")
     .buffer(100) // 100 meters around the route
     .build());

 // 3. Get weather forecast
 WeatherForecast weather = service.getWeatherForecast(new Coordinate(41.3851, 2.1734));
See Also:

  • Constructor Details

    • PoiService

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

  • Method Details

    • searchNearest

      @NotNull public @NotNull List<Poi> searchNearest(@NotNull @NotNull Coordinate center, @NotNull @NotNull PoiNearestOptions options)
      Get the nearest POIs by straight-line distance.
      Parameters:
      center - the search center coordinate
      options - the search options (categories, limit, radius)
      Returns:
      list of POI results ordered by proximity
      Throws:
      CercaliaException - if the request fails

    • searchNearestAsync

      @NotNull public @NotNull CompletableFuture<List<Poi>> searchNearestAsync(@NotNull @NotNull Coordinate center, @NotNull @NotNull PoiNearestOptions options)
      Get the nearest POIs by straight-line distance asynchronously.
      Parameters:
      center - the search center coordinate
      options - the search options
      Returns:
      CompletableFuture with list of POI results

    • searchNearestWithRouting

      @NotNull public @NotNull List<Poi> searchNearestWithRouting(@NotNull @NotNull Coordinate center, @NotNull @NotNull PoiNearestWithRoutingOptions options)
      Get the nearest POIs using routing distance/time.
      Parameters:
      center - the search center coordinate
      options - the search options including routing weight
      Returns:
      list of POI results with routing info
      Throws:
      CercaliaException - if the request fails

    • searchNearestWithRoutingAsync

      @NotNull public @NotNull CompletableFuture<List<Poi>> searchNearestWithRoutingAsync(@NotNull @NotNull Coordinate center, @NotNull @NotNull PoiNearestWithRoutingOptions options)
      Get the nearest POIs using routing distance/time asynchronously.
      Parameters:
      center - the search center coordinate
      options - the search options
      Returns:
      CompletableFuture with list of POI results

    • searchAlongRoute

      @NotNull public @NotNull List<Poi> searchAlongRoute(@NotNull @NotNull PoiAlongRouteOptions options)
      Get POIs along a route.
      Parameters:
      options - the route and search options
      Returns:
      list of POIs along the route
      Throws:
      CercaliaException - if the request fails

    • searchAlongRouteAsync

      @NotNull public @NotNull CompletableFuture<List<Poi>> searchAlongRouteAsync(@NotNull @NotNull PoiAlongRouteOptions options)
      Get POIs along a route asynchronously.
      Parameters:
      options - the route and search options
      Returns:
      CompletableFuture with list of POIs

    • searchInExtent

      @NotNull public @NotNull List<Poi> searchInExtent(@NotNull @NotNull MapExtent extent, @NotNull @NotNull PoiInExtentOptions options)
      Get POIs inside a map extent.
      Parameters:
      extent - the map extent (upper-left and lower-right corners)
      options - the search options
      Returns:
      list of POIs in the extent
      Throws:
      CercaliaException - if the request fails

    • searchInExtentAsync

      @NotNull public @NotNull CompletableFuture<List<Poi>> searchInExtentAsync(@NotNull @NotNull MapExtent extent, @NotNull @NotNull PoiInExtentOptions options)
      Get POIs inside a map extent asynchronously.
      Parameters:
      extent - the map extent
      options - the search options
      Returns:
      CompletableFuture with list of POIs

    • searchInPolygon

      @NotNull public @NotNull List<Poi> searchInPolygon(@NotNull @NotNull PoiInPolygonOptions options)
      Get POIs inside a polygon.
      Parameters:
      options - the polygon and category options
      Returns:
      list of POIs inside the polygon
      Throws:
      CercaliaException - if the request fails

    • searchInPolygonAsync

      @NotNull public @NotNull CompletableFuture<List<Poi>> searchInPolygonAsync(@NotNull @NotNull PoiInPolygonOptions options)
      Get POIs inside a polygon asynchronously.
      Parameters:
      options - the polygon and category options
      Returns:
      CompletableFuture with list of POIs

    • getWeatherForecast

      @Nullable public @Nullable WeatherForecast getWeatherForecast(@NotNull @NotNull Coordinate center)
      Get weather forecast for a location.
      Parameters:
      center - the location coordinate
      Returns:
      the weather forecast, or null if not available
      Throws:
      CercaliaException - if the request fails

    • getWeatherForecastAsync

      @NotNull public @NotNull CompletableFuture<WeatherForecast> getWeatherForecastAsync(@NotNull @NotNull Coordinate center)
      Get weather forecast for a location asynchronously.
      Parameters:
      center - the location coordinate
      Returns:
      CompletableFuture with the weather forecast