Custom styles

Make a style in the console under Styles. Start from a template, the light or dark basemap, or a MapLibre style you import, and edit it in the Studio. Edits save as a draft; Publish makes a version, and maps load the published one. You can roll back to any earlier version.

9:41

Tareky Console

Use it

style: 'https://api.tareky.com/v1/styles/{handle}/{styleId}.json?access_token=tareky_pk_…'

• {handle} is your organisation’s handle. Once you have a style, it can’t change.
• Loading the style is one map load, like the basemap.
• Only your organisation’s keys can load it, unless you make it public.

Static maps and raster tiles draw it too, at the basemap’s prices:

GET /v1/styles/{handle}/{styleId}/static/{lng},{lat},{zoom}/{width}x{height}[@2x][.webp|.png|.jpeg]
GET /v1/styles/{handle}/{styleId}/tiles/{z}/{x}/{y}[@2x][.webp|.png|.jpeg]

They take the static map’s path and pin; labels are in the style’s own language.

With the SDK: customStyleUrl(handle, styleId, { key }), and staticMapUrl({ key, style: { handle, styleId }, center, width, height }).

Imported styles

An imported style is MapLibre JSON. Every address in it is a name of ours, never a URL, and the API checks it against an allowlist: a key the allowlist does not list is refused, not ignored. The limits are in the Studio’s page.

• Style keys: version, name, metadata, center, centerAltitude, zoom, bearing, pitch, roll, state, light, sky, projection, transition, glyphs, sources, layers, and the two that have a rule of their own: sprite is "tareky://sprite" and terrain is { "source", "exaggeration" }.
• Glyphs: "glyphs": "tareky://glyphs/{fontstack}/{range}".
• Layers: id, type, metadata, source, source-layer, minzoom, maxzoom, filter, layout, paint, and every property the MapLibre style spec defines for them. The spec’s own validator checks every layer, filter and expression.
• Publishing draws a test image first. A style our renderer can’t draw is refused, with the reasons.

The Studio exports the style with the tareky:// names, and importing it needs no changes. The simple editor’s export carries our servers’ real addresses, so editors like Maputnik can show it; importing that puts the names back.

Sources

Source type	Where its tiles or data come from
vector	tareky://basemap, tareky://traffic, or one of your tilesets
raster	tareky://satellite, or one of your raster tilesets
raster-dem	tareky://terrain, or one of your elevation tilesets
geojson	inline data, or "data": "tareky://aqi"

"sources": {
  "base": { "type": "vector", "url": "tareky://basemap" },
  "relief": { "type": "raster-dem", "url": "tareky://terrain" },
  "air": { "type": "geojson", "data": "tareky://aqi" }
}

• Your tilesets are tareky://tilesets/{handle}.{name}, and must be your own organisation’s, built, and of the kind the source says. A style that names another organisation’s, or one still building, is refused. See your data.
• tareky://terrain is Iraq’s elevation, where we serve it. A style that names it where it is not served loses the source and the layers that draw it, instead of failing to load.
• tareky://traffic is live traffic: one traffic layer of lines in the direction of travel, zooms 8 to 16. It needs a key with the traffic API and its tiles are billed as there. Load the style with ?access_token=tareky_pk_… and the same key is put on the traffic tiles for you.
• tareky://aqi is Iraq’s air quality as GeoJSON points with an aqi from 1 to 5, refreshed every 15 minutes. It needs no key and costs nothing.
• Source keys allowed: type, url, bounds, minzoom, maxzoom, scheme, tileSize, encoding, attribution, promoteId, volatile. We set an elevation source’s encoding and a tileset’s tile size ourselves.
• An attribution you write is plain text: < and > are removed, because maps show it as HTML. The credits of the basemap, satellite, elevation and air quality are ours to write.
• GeoJSON is inline only, or tareky://aqi. No other URLs.

3D terrain, sky, light and projection

terrain at the root turns an elevation source into 3D relief, and sky, light and projection are the style spec’s:

"terrain": { "source": "relief", "exaggeration": 1.2 },
"sky": { "sky-color": "#bcd7ea", "horizon-fog-blend": 0.5 },
"projection": { "type": "globe" }

• terrain.source names a raster-dem source of the style: tareky://terrain or one of your elevation tilesets.
• A hillshade layer on the same source shades the relief without 3D.
• Static maps and raster tiles draw terrain flat. Our renderer for images has hillshade and extrusions but no 3D terrain, sky or projection, so they are left out of the image and the map is seen flat from above, shaded by its hillshade layers if it has any. The response says so with a header, X-Style-Degraded: terrain. Live traffic and air quality are not drawn in images either: a renderer has no key, and it fetches nothing from outside.
• The elevation is Copernicus DEM GLO-30. Any map that draws it must show this credit. The tareky://terrain source already carries it, so MapLibre and static maps print it:

Produced using Copernicus WorldDEM-30 © DLR e.V. 2010-2014 and © Airbus Defence and Space GmbH 2014-2018 provided under COPERNICUS by the European Union and ESA; all rights reserved

The organisations of the Copernicus programme accept no liability for any use of this data. If you redistribute the elevation, say so too.

Fonts

A style draws text in Noto Sans Regular, Noto Sans Bold, Noto Sans Arabic Regular and Noto Sans Arabic Bold, or in your own fonts.

Upload: in the Studio’s Fonts tab, choose a TTF, OTF or WOFF file of up to 10 MB, name its stack (letters, digits, space, ., _ and -, up to 64 characters; the four fonts above are taken), and tick the licence statement: you hold a licence that lets the font be used in maps and its glyphs be shared. Without it the upload is refused. The font goes to storage, then our font worker turns it into the glyph files a map draws text from. It shows PROCESSING, then READY or FAILED with the reason.

• WOFF2 and font collections (.ttc) are not supported.
• A font that is empty, unreadable, too complex (glyphs larger or more detailed than a map can use) or slow to convert is FAILED.
• Quota: your plan sets how many fonts you keep (3 on the free plan). A failed font does not count.
• Delete: a font can’t be deleted while a published style names it (font_in_use).
• Takedown: if we receive a licence or abuse complaint we can remove a font, with the reason in your activity log and by email to your owners. A published style that names it stops being served until you publish one that does not.

Use: the stack name goes in text-font, bare or as a name of ours:

"layout": { "text-font": ["tareky://glyphs/acme.Cairo Bold", "Noto Sans Arabic Bold"] }

A fallback list works as in MapLibre: a character the first font lacks is drawn from the next. When a layer uses one of your fonts, the served style points glyphs at your organisation’s glyph route:

GET /v1/styles/glyphs/{handle}/{fontstack}/{range}.pbf

It is public, unmetered and rate limited. fontstack is a comma-separated list (up to 8) of your fonts and the platform’s, composed in the order the layer lists them. A font that is not READY is skipped, so a label falls back to the next font instead of vanishing, and a list with nothing to draw with answers 404. With ?v= (the served style adds it) the answer is cached for good; without it, for an hour.

Icons

Add icons to an imported style in the Studio’s Icons tab, then draw them by name:

"sprite": "tareky://sprite",
"layers": [{ "id": "shops", "type": "symbol", "source": "shops", "layout": { "icon-image": "shop" } }]

• SVG: up to 32 KB, drawn at most 64 pixels a side. Scripts, images, styles and links outside the icon are refused, with the reason.
• PNG: up to 32 KB and 256×256 pixels. Say whether it was drawn for 2× screens (pixelRatio 2) and we halve it for 1× screens.
• SDF: tick it and the icon is drawn as a distance field, so icon-color works on it. It suits one-colour icons.
• A name is letters, digits, - and _ (up to 64), and a style holds up to 64 icons (your plan sets it).
• The icon library: about forty generic map icons (pin, home, work, restaurant, cafe and more), with Arabic and English names, drawn for this project and free to use under CC0. Add one by name. They are solid black, so they work as SDF icons.
• Publishing freezes the icons into that version’s sprite, at 1× and 2×. It is served from /v1/styles/{handle}/{id}/sprites/…, free and cached for good, so a published map keeps its icons even if you change them later.

Limits

• Your plan sets how many styles you can keep, and how big one may be: its size, layers and icons (the Studio).
• Static images and tiles of custom styles are drawn one at a time per organisation. A drawing that takes more than 30 seconds is answered 503, and that style is paused for you for ten minutes.