@cercalia/sdk
    Preparing search index...

    Class StaticMapsService

    StaticMapsService - Generate static map images with markers, shapes and labels

    Based on the Cercalia Static Maps API: https://docs.cercalia.com/docs/cercalia-webservices/static-maps/

    Features:

    • Paint markers on the map
    • Draw shapes: circles, rectangles, sectors, lines, polylines
    • Add labels
    • Get image URL or raw image data

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    config

    Methods

    downloadImage generateCityMap generateMap generateMapAsImage generateMapWithCircle generateMapWithLabel generateMapWithLine generateMapWithMarkers generateMapWithPolyline generateMapWithRectangle generateMapWithSector request

    Constructors

    Properties

    config: CercaliaConfig

    Configuration for the Cercalia API connection.

    Methods

    • Download the static map image as a buffer

      Parameters

      • imageUrl: string

      Returns Promise<ArrayBuffer>

      const result = await staticMaps.generateCityMap('Barcelona', 'ESP');
      const imageBuffer = await staticMaps.downloadImage(result.imageUrl);
      // Save to file or send as response

    • Generate a map centered on a city with a label

      Parameters

      • cityName: string
      • countryCode: string = 'ESP'
      • Optionaloptions: { height?: number; width?: number }

      Returns Promise<StaticMapResult>

      const result = await staticMaps.generateCityMap('Girona', 'ESP', { width: 350, height: 250 });
      logger.info(result.imageUrl); // Full URL to download the image

    • Generate a static map with optional markers and shapes

      Parameters

      Returns Promise<StaticMapResult>

      const result = await staticMaps.generateMap({
        cityName: 'girona',
        countryCode: 'ESP',
        width: 350,
        height: 250,
      });

      const result = await staticMaps.generateMap({
        width: 400,
        height: 300,
        extent: {
          upperLeft: { lat: 41.439132726, lng: 2.003108336 },
          lowerRight: { lat: 41.390497829, lng: 2.197135455 },
        },
        shapes: [
          {
            type: 'CIRCLE',
            outlineColor: { r: 255, g: 0, b: 0, a: 128 },
            outlineSize: 2,
            fillColor: { r: 0, g: 255, b: 0, a: 128 },
            center: { lat: 41.439132726, lng: 2.003108336 },
            radius: 2000,
          },
          {
            type: 'POLYLINE',
            outlineColor: { r: 255, g: 0, b: 0 },
            outlineSize: 2,
            fillColor: { r: 255, g: 0, b: 0 },
            coordinates: [
              { lat: 41.401902461, lng: 2.142455003 },
              { lat: 41.404628181, lng: 2.155965665 },
              { lat: 41.433339308, lng: 2.179860852 },
            ],
          },
        ],
      });

    • Generate map and return image data directly

      Parameters

      Returns Promise<StaticMapResult>

      const result = await staticMaps.generateMapAsImage({
        cityName: 'Barcelona',
        countryCode: 'ESP',
        width: 400,
        height: 300,
      });
      // result.imageData contains the raw image bytes

    • Generate a map with a circle shape

      Parameters

      • center: Coordinate
      • radius: number
      • Optionalstyle: { fillColor?: RGBAColor; outlineColor?: RGBAColor; outlineSize?: number }
      • Optionaloptions: { height?: number; width?: number }

      Returns Promise<StaticMapResult>

      const result = await staticMaps.generateMapWithCircle(
        { lat: 41.439132726, lng: 2.003108336 },
        2000, // radius in meters
        {
          outlineColor: { r: 255, g: 0, b: 0, a: 128 },
          fillColor: { r: 0, g: 255, b: 0, a: 128 },
        }
      );

    • Generate a map with a label at a specific position

      Parameters

      • center: Coordinate
      • text: string
      • Optionalstyle: { fillColor?: RGBAColor; outlineColor?: RGBAColor; outlineSize?: number }
      • Optionaloptions: { height?: number; width?: number }

      Returns Promise<StaticMapResult>

      const result = await staticMaps.generateMapWithLabel(
        { lat: 41.3851, lng: 2.1734 },
        'Barcelona',
      );

    • Generate a map with a line between two points

      Parameters

      • start: Coordinate
      • end: Coordinate
      • Optionalstyle: { outlineColor?: RGBAColor; outlineSize?: number }
      • Optionaloptions: { height?: number; width?: number }

      Returns Promise<StaticMapResult>

      const result = await staticMaps.generateMapWithLine(
        { lat: 41.3851, lng: 2.1734 },
        { lat: 41.4034, lng: 2.1741 },
      );

    • Generate a map with markers

      Parameters

      • markers: StaticMapMarker[]
      • Optionaloptions: { height?: number; width?: number }

      Returns Promise<StaticMapResult>

      const result = await staticMaps.generateMapWithMarkers([
        { coord: { lat: 41.3851, lng: 2.1734 }, icon: 1 },
        { coord: { lat: 41.4034, lng: 2.1741 }, icon: 2 },
      ]);

    • Generate a map with a polyline

      Parameters

      • coordinates: Coordinate[]
      • Optionalstyle: { outlineColor?: RGBAColor; outlineSize?: number }
      • Optionaloptions: { height?: number; width?: number }

      Returns Promise<StaticMapResult>

      const result = await staticMaps.generateMapWithPolyline([
        { lat: 41.401902461, lng: 2.142455003 },
        { lat: 41.404628181, lng: 2.155965665 },
        { lat: 41.433339308, lng: 2.179860852 },
      ]);

    • Generate a map with a rectangle shape

      Parameters

      • upperLeft: Coordinate
      • lowerRight: Coordinate
      • Optionalstyle: { fillColor?: RGBAColor; outlineColor?: RGBAColor; outlineSize?: number }
      • Optionaloptions: { cityName?: string; height?: number; width?: number }

      Returns Promise<StaticMapResult>

      const result = await staticMaps.generateMapWithRectangle(
        { lat: 41.98, lng: 2.82 }, // upper left
        { lat: 41.96, lng: 2.84 }, // lower right
      );

    • Generate a map with a sector shape

      Parameters

      • center: Coordinate
      • innerRadius: number
      • outerRadius: number
      • startAngle: number
      • endAngle: number
      • Optionalstyle: { fillColor?: RGBAColor; outlineColor?: RGBAColor; outlineSize?: number }
      • Optionaloptions: { height?: number; width?: number }

      Returns Promise<StaticMapResult>

      const result = await staticMaps.generateMapWithSector(
        { lat: 41.3851, lng: 2.1734 },
        500, // inner radius
        1000, // outer radius
        0, // start angle
        90, // end angle
      );

    • Executes a generic request to the Cercalia API.

      Type Parameters

      • T

      Parameters

      • params: Record<string, string>

        Query parameters for the API request.

      • operationName: string = 'Cercalia Request'

        Human-readable name for logging and debugging.

      • OptionalbaseUrl: string

        Optional override for the base API URL.

      Returns Promise<T>

      A promise resolving to the parsed API response.

      Error with code '30006' when no results are found.

      Error for HTTP errors or invalid JSON responses.

      const response = await this.request<MyResponse>(
        { cmd: 'cand', adr: 'Gran Via 1' },
        'Geocoding'
      );

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods