Package com.cercalia.sdk.services

Class StaticMapsService

java.lang.Object
com.cercalia.sdk.CercaliaClient
com.cercalia.sdk.services.StaticMapsService
public class StaticMapsService extends CercaliaClient
StaticMapsService - Generates static map images with markers, shapes, and labels.

This service allows you to create custom map images centered on coordinates or cities, with various overlays like markers, circles, polylines, and rectangles.

Example usage: 


 StaticMapsService service = new StaticMapsService(config);
 
 // Simple map centered on a city
 StaticMapResult result = service.generateCityMap("Barcelona", "ESP", 800, 600);
 String url = result.getImageUrl();
 
 // Complex map with markers and shapes
 StaticMapOptions options = StaticMapOptions.builder()
     .center(new Coordinate(41.38, 2.17))
     .width(1024)
     .height(768)
     .addMarker(StaticMapMarker.builder(new Coordinate(41.38, 2.17)).label("Center").build())
     .addShape(StaticMapCircle.builder(new Coordinate(41.38, 2.17), 500).fillColor("AA0000").build())
     .build();
 
 StaticMapResult complexResult = service.generateMap(options);
 byte[] imageData = service.downloadImage(complexResult.getImageUrl());
See Also:

  • Constructor Details

    • StaticMapsService

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

  • Method Details

    • generateMap

      @NotNull public @NotNull StaticMapResult generateMap(@NotNull @NotNull StaticMapOptions options)
      Generate a static map with optional markers and shapes.
      Parameters:
      options - the map generation options
      Returns:
      the generated map result
      Throws:
      CercaliaException - if the request fails

    • generateMapAsync

      @NotNull public @NotNull CompletableFuture<StaticMapResult> generateMapAsync(@NotNull @NotNull StaticMapOptions options)
      Generate a static map asynchronously.
      Parameters:
      options - the map generation options
      Returns:
      CompletableFuture with the result

    • generateCityMap

      @NotNull public @NotNull StaticMapResult generateCityMap(@NotNull @NotNull String cityName, @NotNull @NotNull String countryCode, @Nullable @Nullable Integer width, @Nullable @Nullable Integer height)
      Generate a map centered on a city with a label.
      Parameters:
      cityName - the city name
      countryCode - the country code (e.g., "ESP")
      width - optional width
      height - optional height
      Returns:
      the generated map result

    • generateCityMap

      @NotNull public @NotNull StaticMapResult generateCityMap(@NotNull @NotNull String cityName, @NotNull @NotNull String countryCode)
      Generate a map centered on a city with default dimensions.

    • generateMapWithCircle

      @NotNull public @NotNull StaticMapResult generateMapWithCircle(@NotNull @NotNull Coordinate center, int radius, @Nullable @Nullable StaticMapCircle circle, @Nullable @Nullable Integer width, @Nullable @Nullable Integer height)
      Generate a map with a circle shape.
      Parameters:
      center - the center coordinate
      radius - the radius in meters
      circle - optional circle style (uses defaults if null)
      width - optional width
      height - optional height
      Returns:
      the generated map result

    • generateMapWithCircle

      @NotNull public @NotNull StaticMapResult generateMapWithCircle(@NotNull @NotNull Coordinate center, int radius)
      Generate a map with a circle shape using default style.

    • generateMapWithRectangle

      @NotNull public @NotNull StaticMapResult generateMapWithRectangle(@NotNull @NotNull Coordinate upperLeft, @NotNull @NotNull Coordinate lowerRight, @Nullable @Nullable StaticMapRectangle rectangle, @Nullable @Nullable String cityName, @Nullable @Nullable Integer width, @Nullable @Nullable Integer height)
      Generate a map with a rectangle shape.
      Parameters:
      upperLeft - the upper left corner
      lowerRight - the lower right corner
      rectangle - optional rectangle style
      cityName - optional city name for centering
      width - optional width
      height - optional height
      Returns:
      the generated map result

    • generateMapWithPolyline

      @NotNull public @NotNull StaticMapResult generateMapWithPolyline(@NotNull @NotNull List<Coordinate> coordinates, @Nullable @Nullable StaticMapPolyline polyline, @Nullable @Nullable Integer width, @Nullable @Nullable Integer height)
      Generate a map with a polyline.
      Parameters:
      coordinates - the polyline coordinates
      polyline - optional polyline style
      width - optional width
      height - optional height
      Returns:
      the generated map result

    • generateMapWithLine

      @NotNull public @NotNull StaticMapResult generateMapWithLine(@NotNull @NotNull Coordinate start, @NotNull @NotNull Coordinate end, @Nullable @Nullable StaticMapLine line, @Nullable @Nullable Integer width, @Nullable @Nullable Integer height)
      Generate a map with a line between two points.
      Parameters:
      start - the start coordinate
      end - the end coordinate
      line - optional line style
      width - optional width
      height - optional height
      Returns:
      the generated map result

    • generateMapWithMarkers

      @NotNull public @NotNull StaticMapResult generateMapWithMarkers(@NotNull @NotNull List<StaticMapMarker> markers, @Nullable @Nullable Integer width, @Nullable @Nullable Integer height)
      Generate a map with markers.
      Parameters:
      markers - the markers to place
      width - optional width
      height - optional height
      Returns:
      the generated map result

    • generateMapWithLabel

      @NotNull public @NotNull StaticMapResult generateMapWithLabel(@NotNull @NotNull Coordinate center, @NotNull @NotNull String text, @Nullable @Nullable Integer width, @Nullable @Nullable Integer height)
      Generate a map with a label at a specific position.
      Parameters:
      center - the label position
      text - the label text
      width - optional width
      height - optional height
      Returns:
      the generated map result

    • generateMapWithSector

      @NotNull public @NotNull StaticMapResult generateMapWithSector(@NotNull @NotNull Coordinate center, int innerRadius, int outerRadius, int startAngle, int endAngle, @Nullable @Nullable Integer width, @Nullable @Nullable Integer height)
      Generate a map with a sector shape.
      Parameters:
      center - the center coordinate
      innerRadius - the inner radius
      outerRadius - the outer radius
      startAngle - the start angle in degrees
      endAngle - the end angle in degrees
      width - optional width
      height - optional height
      Returns:
      the generated map result

    • downloadImage

      @NotNull public @org.jetbrains.annotations.NotNull byte[] downloadImage(@NotNull @NotNull String imageUrl)
      Download the static map image as a byte array.
      Parameters:
      imageUrl - the image URL
      Returns:
      the image bytes
      Throws:
      CercaliaException - if download fails

    • generateMapAsImage

      @NotNull public @NotNull StaticMapResult generateMapAsImage(@NotNull @NotNull StaticMapOptions options)
      Generate map and return image data directly.
      Parameters:
      options - the map generation options (returnImage is ignored)
      Returns:
      the result with imageData populated