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.

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.tsimport 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.tsimport { 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' : '';
}
} The React version uses the library's React adapter, cc-openlayers/react: each component creates the OpenLayers object it names when it mounts, updates it from its props and disposes of it when it unmounts.
vector-esri.react.tsximport { useCallback, useRef, useState } from 'react';
import type OLMap from 'ol/Map.js';
import type MapBrowserEvent from 'ol/MapBrowserEvent.js';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
ImageTileSource,
Map,
TileLayer,
VectorLayer,
VectorSource,
View,
} from 'cc-openlayers/react';
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. */
export function VectorEsriReact() {
const map = useRef<OLMap>(null);
const [info, setInfo] = useState(NO_MUNICIPALITY_INFO);
const show = useCallback((event: MapBrowserEvent) => {
if (event.dragging) return;
const current = map.current;
if (!current) return;
const feature = current.forEachFeatureAtPixel(event.pixel, (hit) => hit);
const nextInfo = feature ? municipalityInfo(feature) : NO_MUNICIPALITY_INFO;
setInfo((previous) => (previous === nextInfo ? previous : nextInfo));
const target = current.getTargetElement();
if (target) target.style.cursor = feature ? 'pointer' : '';
}, []);
return (
<>
<Map
ref={map}
height="480px"
ariaLabel="ArcGIS REST municipalities around Kraków"
onPointerMove={show}
onClick={show}
>
<DefaultInteractions />
<DefaultControls attributionOptions={ATTRIBUTION_OPTIONS} />
<View zoom={12} minZoom={10} maxZoom={19}>
<Coordinate x={19.9368} y={50.0614} srid="EPSG:4326" />
</View>
<TileLayer>
<ImageTileSource url={WORLD_TOPO_MAP_URL} attributions={WORLD_TOPO_MAP_CREDIT} />
</TileLayer>
<VectorLayer opacity={0.7} style={municipalityStyle}>
<VectorSource
url={municipalityQueryUrl}
format={municipalityFormat}
strategy={municipalityTileStrategy}
wrapX={false}
attributions={MUNICIPALITY_CREDIT}
/>
</VectorLayer>
</Map>
<div className="example-controls">
<output aria-live="polite" style={{ whiteSpace: 'pre-line' }}>
{info}
</output>
</div>
</>
);
}vector-esri.shared.tsimport 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') ?? '')}`;
}How the React version works
Both examples load PRG municipalities around Kraków as EsriJSON from the public GIOŚ ArcGIS REST service. A global 512-pixel tile strategy supplies request envelopes; the existing arcGisQueryUrl helper declares their projection, output fields and geometry projection. Geometry is generalized to the display resolution. The map uses Esri’s topographic basemap and retains the credits of both sources. This retains the upstream example’s service-query, vector-decoding, attribute-style and pointer/click behaviors with a different dataset. It does not reproduce the British 1965/2014 land-use comparison. The fields shown here are the municipality name and the service’s district identifier.
What both versions share
The service’s feature set contains FID as an OID field but omits objectIdFieldName. A municipality-specific EsriJSON adapter assigns each decoded feature its FID. Adjacent tile envelopes can then return the same polygon without adding it twice. The framework adapters keep ownership of the source, map, layers and disposal; the example does not create another transport client. Both consume public map events, ignore pointer movement during dragging and render attribute values as text. No-hit events restore the instruction and default cursor.
From Angular to React
| Angular | React |
|---|---|
<aol-source-vector [url] [format] [strategy]> | <VectorSource url format strategy> with the same module constants |
signal for the selected municipality | useState for the selected municipality |
Public map event outputs and viewChild | Public map callbacks and a map ref |
Who creates, updates and disposes
The map, layer and source components own their OpenLayers objects. Angular destruction and React effect cleanup dispose the map and source; neither example owns a second map or transport. React keeps the map ref current across StrictMode effect replay and updates only the selected information in view state.
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
NAMEandDISTRICT_I, withFIDpromoted 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
FIDcompensates for the server omittingobjectIdFieldNameand 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
3857or 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.
Related examples
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.