---
title: "Raster tiles in OpenLayers | Openlayers"
description: "Display raster tiles in OpenLayers via TileJSON or XYZ."
---
> For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL.
# Raster tiles in OpenLayers
Raster tiles maps are actually nothing else than raster images. Zoomable raster maps consist of many raster map tiles (in the .png or .jpg format) placed next to each other, ordered in a pyramid scheme. This clever trick allows you to browse just a small part of the map without loading it whole while maintaining the feeling of exploring a single large document. Read more about zoomable maps and the pyramid scheme in [this article](https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection/).
Use **recommended 512x512** raster tiles with TileJSON or XYZ.
Next, we will explain two ways how to create a map in OpenLayers using your MapTiler maps.
The first way is to use the TileJSON source function; this function is in charge of interpreting the TileJson file and creating the source with all the options and metadata. In a second way, we have to use the XYZ source; in this case, we must indicate the URL of the tiles that we want to load in our map and we will not have any metadata associated with the source.
## Raster tiles TileJSON
Raster tiles TileJSON are loaded with [TileJSON](https://openlayers.org/en/latest/apidoc/module-ol_source_TileJSON-TileJSON.html) function. Start your code with the following starter:
```html
```
```js
import Map from 'ol/Map.js';
import View from 'ol/View.js';
import TileLayer from 'ol/layer/Tile.js';
import TileJSON from 'ol/source/TileJSON.js';
import Attribution from 'ol/control/Attribution.js';
import { defaults as defaultControls } from 'ol/control/defaults.js';
import { fromLonLat } from 'ol/proj.js';
import 'ol/ol.css';
const key = 'YOUR_MAPTILER_API_KEY_HERE';
const source = new TileJSON({
url: `https://api.maptiler.com/maps/streets-v4/tiles.json?key=${key}`,
tileSize: 512,
crossOrigin: 'anonymous'
});
const attribution = new Attribution({
collapsible: false,
});
const map = new Map({
layers: [
new TileLayer({
source: source
})
],
controls: defaultControls({attribution: false}).extend([attribution]),
target: 'map',
view: new View({
constrainResolution: true,
center: fromLonLat([0, 0]),
zoom: 2
})
});
```
Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [secure the key](https://docs.maptiler.com/guides/developer/credentials/api-key/#secure-key) before you publish it.
Use **256x256** raster tiles for compatibility with certain libraries. To use the 256px tiles you must use this URL in your layer
```http
`https://api.maptiler.com/maps/streets-v4/256/tiles.json?key=${key}`
```
Example of 256x256 raster tiles
```js
const source = new ol.source.TileJSON({
url: `https://api.maptiler.com/maps/streets-v4/256/tiles.json?key=${key}`,
crossOrigin: 'anonymous'
});
```
```js
const source = new TileJSON({
url: `https://api.maptiler.com/maps/streets-v4/256/tiles.json?key=${key}`,
crossOrigin: 'anonymous'
});
```
## Raster tiles XYZ (Mercator XYZ)
Raster tiles (Mercator XYZ) are loaded with [XYZ](https://openlayers.org/en/latest/apidoc/module-ol_source_XYZ-XYZ.html) function. Start your code with the following starter:
```html
```
```js
import Map from 'ol/Map.js';
import View from 'ol/View.js';
import TileLayer from 'ol/layer/Tile.js';
import Attribution from 'ol/control/Attribution.js';
import XYZ from 'ol/source/XYZ.js';
import { defaults as defaultControls } from 'ol/control/defaults.js';
import { fromLonLat } from 'ol/proj.js';
import 'ol/ol.css';
const key = 'YOUR_MAPTILER_API_KEY_HERE';
const source = new XYZ({
url: `https://api.maptiler.com/maps/streets-v4/{z}/{x}/{y}.png?key=${key}`,
tileSize: 512,
crossOrigin: 'anonymous'
});
const attribution = new Attribution({
collapsible: false,
});
const map = new Map({
layers: [
new TileLayer({
source: source
})
],
controls: defaultControls({attribution: false}).extend([attribution]),
target: 'map',
view: new View({
constrainResolution: true,
center: fromLonLat([0, 0]),
zoom: 2
})
});
```
Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [secure the key](https://docs.maptiler.com/guides/developer/credentials/api-key/#secure-key) before you publish it.
Use **256x256** raster tiles for compatibility with certain libraries. To use the 256px tiles you must use this URL in your layer
```http
`https://api.maptiler.com/maps/streets-v4/256/{z}/{x}/{y}.png?key=${key}`
```
Example of 256x256 raster tiles
```js
const source = new ol.source.XYZ({
url: `https://api.maptiler.com/maps/streets-v4/256/{z}/{x}/{y}.png?key=${key}`,
crossOrigin: 'anonymous'
});
```
```js
const source = new XYZ({
url: `https://api.maptiler.com/maps/streets-v4/256/{z}/{x}/{y}.png?key=${key}`,
crossOrigin: 'anonymous'
});
```
### Summary
The two ways of working with raster layers are very similar, the advantages of using TileJson (**recommended option**) are that we have more information associated with the data source (metadata) and if the service provider changes any metadata our application will always be synchronized and working.
## Related examples
### [Custom Map](https://docs.maptiler.com/openlayers/examples/custom-map/)
Tutorials
Display custom MapTiler maps on webpages using OpenLayers.
### [OGC WMTS service](https://docs.maptiler.com/openlayers/examples/wmts/)
Tutorials
Use OGC WMTS services in OpenLayers web maps.
