Vector data · Angular, React and OpenLayers

ArcGIS REST features loaded by tile extent

Query PRG Polish municipality polygons by 512px tile envelopes from an ArcGIS REST Feature/MapServer in OpenLayers and decode EsriJSON.

PRG municipality polygons around Kraków over Esri’s topographic map, with an area for the selected municipality’s attributes below.
A screenshot of the example. PRG: Główny Urząd Geodezji i Kartografii; service: GIOŚ. Base map: Esri World Topographic Map (Esri, HERE, Garmin, Intermap, increment P Corp., GEBCO, USGS, FAO, NPS, NRCAN, GeoBase, IGN, Kadaster NL, Ordnance Survey, Esri Japan, METI, Esri China (Hong Kong), OpenStreetMap contributors and the GIS User Community).

What this example shows

Over Esri’s World Topographic Map around Kraków, official Polish Register of Borders (PRG) municipality polygons stream tile by tile as vector EsriJSON from GIOŚ’s public ArcGIS MapServer, with the central district highlighted in cream.

Hovering or clicking any commune displays its municipality name and district ID below the map while active pan drags leave the current readout undisturbed.

When you need it

Many environmental, utility and municipal agencies expose vector attributes and geometries through ArcGIS REST /query endpoints (f=json) rather than OGC WFS.

Combining a 512-pixel tile loading strategy with OpenLayers’ EsriJSON decoder turns dynamic ArcGIS /query envelopes into cacheable client-side vector polygons with instant hover inspection.

The code

The example uses cc-openlayers, my Angular component library for OpenLayers: each aol-… element creates the OpenLayers object it names, updates it from its inputs and disposes of it with the component.

vector-esri.html
<aol-map
  height="480px"
  ariaLabel="ArcGIS REST municipalities around Kraków"
  (pointerMove)="show($event)"
  (olClick)="show($event)"
>
  <aol-interaction-default />
  <aol-control-defaults [attributionOptions]="attributionOptions" />
  <aol-view [zoom]="12" [minZoom]="10" [maxZoom]="19">
    <aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" />
  </aol-view>
  <aol-layer-tile>
    <aol-source-imagetile [url]="worldTopoMapUrl" [attributions]="worldTopoMapCredit" />
  </aol-layer-tile>
  <aol-layer-vector [opacity]="0.7" [style]="style">
    <aol-source-vector
      [url]="url"
      [format]="format"
      [strategy]="strategy"
      [wrapX]="false"
      [attributions]="municipalityCredit"
    />
  </aol-layer-vector>
</aol-map>
<div class="example-controls">
  <output aria-live="polite">{{ info() }}</output>
</div>
vector-esri.scss
.example-controls output {
  white-space: pre-line;
}
vector-esri.shared.ts
import type Feature from 'ol/Feature.js';
import type { FeatureLike } from 'ol/Feature.js';
import type { Extent } from 'ol/extent.js';
import EsriJSON from 'ol/format/EsriJSON.js';
import type { ReadOptions } from 'ol/format/Feature.js';
import { tile } from 'ol/loadingstrategy.js';
import type Projection from 'ol/proj/Projection.js';
import Fill from 'ol/style/Fill.js';
import type { StyleFunction } from 'ol/style/Style.js';
import Style from 'ol/style/Style.js';
import Stroke from 'ol/style/Stroke.js';
import { createXYZ } from 'ol/tilegrid.js';
import { arcGisQueryUrl } from 'cc-openlayers/services';

export const MUNICIPALITY_LAYER_URL =
  'https://wody.gios.gov.pl/arcgis/rest/services/MPP/AdministrativeDivisionSHP/MapServer/2';

export const MUNICIPALITY_CREDIT =
  'PRG: <a href="https://www.gov.pl/web/gugik" target="_blank" rel="noopener">Główny Urząd Geodezji i Kartografii</a>; ' +
  'service: <a href="https://wody.gios.gov.pl/arcgis/rest/services/MPP/AdministrativeDivisionSHP/MapServer/2" ' +
  'target="_blank" rel="noopener">GIOŚ</a>';

export const WORLD_TOPO_MAP_URL =
  'https://server.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/tile/{z}/{y}/{x}';

export const WORLD_TOPO_MAP_CREDIT =
  'Tiles © <a href="https://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer" ' +
  'target="_blank" rel="noopener">ArcGIS</a>';

export const ATTRIBUTION_OPTIONS = { collapsible: false } as const;
export const NO_MUNICIPALITY_INFO = 'Move over a municipality or click it to see its name and district code.';

/** The returned EsriJSON omits objectIdFieldName, so this layer uses its documented FID field for stable IDs. */
export class PrgMunicipalitiesFormat extends EsriJSON {
  override readFeatures(source: Parameters<EsriJSON['readFeatures']>[0], options?: ReadOptions): Feature[] {
    const features = super.readFeatures(source, options);
    for (const feature of features) {
      const fid = feature.get('FID');
      if (typeof fid === 'number' || typeof fid === 'string') feature.setId(fid);
    }
    return features;
  }
}

export const municipalityFormat = new PrgMunicipalitiesFormat();

/** A global EPSG:3857 XYZ grid with the original example's 512 pixel logical tile size. */
export const municipalityTileStrategy = tile(createXYZ({ tileSize: 512 }));

/** A bounded EsriJSON query for the tile extent in its current view projection. */
export function municipalityQueryUrl(extent: Extent, resolution: number, projection: Projection): string {
  return arcGisQueryUrl(
    MUNICIPALITY_LAYER_URL,
    {
      extent,
      extentProjection: projection,
      featureProjection: projection,
      outFields: ['FID', 'NAME', 'DISTRICT_I'],
    },
    { maxAllowableOffset: String(resolution), geometryPrecision: '1' }
  );
}

const centralMunicipality = new Style({
  fill: new Fill({ color: '#f7f7e9' }),
  stroke: new Stroke({ color: '#8c8b8b', width: 1 }),
});
const otherMunicipality = new Style({
  fill: new Fill({ color: '#d9e5c8' }),
  stroke: new Stroke({ color: '#8c8b8b', width: 1 }),
});

export const municipalityStyle: StyleFunction = (feature) =>
  feature.get('DISTRICT_I') === 1261 ? centralMunicipality : otherMunicipality;

export function municipalityInfo(feature: FeatureLike): string {
  return `Municipality: ${String(feature.get('NAME') ?? '')}\nDistrict code: ${String(feature.get('DISTRICT_I') ?? '')}`;
}
vector-esri.ts
import { ChangeDetectionStrategy, Component, signal, viewChild } from '@angular/core';
import type MapBrowserEvent from 'ol/MapBrowserEvent.js';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerTileComponent,
  LayerVectorComponent,
  MapComponent,
  SourceImageTileComponent,
  SourceVectorComponent,
  ViewComponent,
} from 'cc-openlayers';
import {
  ATTRIBUTION_OPTIONS,
  MUNICIPALITY_CREDIT,
  NO_MUNICIPALITY_INFO,
  WORLD_TOPO_MAP_CREDIT,
  WORLD_TOPO_MAP_URL,
  municipalityFormat,
  municipalityInfo,
  municipalityQueryUrl,
  municipalityStyle,
  municipalityTileStrategy,
} from './vector-esri.shared';

/** ArcGIS REST municipality polygons around Kraków, loaded and identified by their PRG feature IDs. */
@Component({
  selector: 'app-vector-esri',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerTileComponent,
    LayerVectorComponent,
    MapComponent,
    SourceImageTileComponent,
    SourceVectorComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  templateUrl: './vector-esri.html',
  styleUrl: './vector-esri.scss',
})
export class VectorEsri {
  readonly info = signal(NO_MUNICIPALITY_INFO);

  protected readonly attributionOptions = ATTRIBUTION_OPTIONS;
  protected readonly municipalityCredit = MUNICIPALITY_CREDIT;
  protected readonly worldTopoMapCredit = WORLD_TOPO_MAP_CREDIT;
  protected readonly worldTopoMapUrl = WORLD_TOPO_MAP_URL;
  protected readonly format = municipalityFormat;
  protected readonly strategy = municipalityTileStrategy;
  protected readonly url = municipalityQueryUrl;
  protected readonly style = municipalityStyle;

  private readonly map = viewChild.required(MapComponent);

  protected show(event: MapBrowserEvent): void {
    if (event.dragging) return;

    const map = this.map().instance;
    const feature = map.forEachFeatureAtPixel(event.pixel, (hit) => hit);
    const nextInfo = feature ? municipalityInfo(feature) : NO_MUNICIPALITY_INFO;
    if (this.info() !== nextInfo) this.info.set(nextInfo);

    const target = map.getTargetElement();
    if (target) target.style.cursor = feature ? 'pointer' : '';
  }
}

Architecture and OpenLayers mechanics

Configured with a global 512-pixel tile strategy, the vector source requests fixed tile envelopes from the GIOŚ ArcGIS REST endpoint—passing explicit input/output spatial references and server-side geometry generalisation matched to the active resolution.

Because this server omits objectIdFieldName metadata in its JSON payload, the custom municipality format promotes each feature’s FID attribute to its canonical OpenLayers feature ID—preventing polygons that straddle multiple 512-pixel query envelopes from being added twice.

How it works

  • GIOŚ’s public ArcGIS MapServer supplies PRG municipality polygons as EsriJSON styled and inspected via NAME and DISTRICT_I, with FID promoted to the feature id for deduplication.
  • A global 512-pixel tile loading strategy bounds each /query envelope while requesting resolution-appropriate geometry generalisation.
  • Assigning each decoded feature its FID compensates for the server omitting objectIdFieldName and deduplicates cross-tile polygons.
  • Pointer hover and click display the municipality’s name and district code while ignoring drag gestures.

Pitfalls

  • Keep your OpenLayers projection code and the numeric ArcGIS wkid (inSR / outSR, such as 3857 or 102100) strictly aligned so envelopes and returned vertices match.
  • Without deterministic feature IDs (FID / OBJECTID), overlapping or adjacent tile queries insert duplicate copies of every boundary-spanning municipality into the vector source.
  • Technical CORS reachability never implies open licensing—always verify statutory data reuse rights (such as GUGiK PRG terms) and display required provider credits.

The same feature in the OpenLayers examples .

Background: state and lifecycle of maps in Angular with OpenLayers, which the components of cc-openlayers take care of.