Skip to content
maplibre-yaml

Basic map

The smallest map with data of your own: five US cities written into the document, drawn as circles sized by population, with a popup when you click one. Read it after the quick start, when you want to see a layer, its data and its styling together.

Click a city for its population

Edit this map in the playground

basic-map.yaml
# yaml-language-server: $schema=https://docs.maplibre-yaml.org/schema/latest/map.schema.json
type: map
id: basic-cities
config:
  center: [-98.5, 39.8]
  zoom: 4
  bounds: [-125, 24, -70, 50]   # west, south, east, north
  mapStyle: "https://tiles.openfreemap.org/styles/liberty"
layers:
  - id: cities
    type: circle
    source:
      type: geojson
      data:
        type: FeatureCollection
        features:
          - type: Feature
            geometry:
              type: Point
              coordinates: [-74.006, 40.7128]
            properties:
              name: "New York"
              population: 8336817
          - type: Feature
            geometry:
              type: Point
              coordinates: [-118.2437, 34.0522]
            properties:
              name: "Los Angeles"
              population: 3979576
          - type: Feature
            geometry:
              type: Point
              coordinates: [-87.6298, 41.8781]
            properties:
              name: "Chicago"
              population: 2693976
          - type: Feature
            geometry:
              type: Point
              coordinates: [-95.3698, 29.7604]
            properties:
              name: "Houston"
              population: 2320268
          - type: Feature
            geometry:
              type: Point
              coordinates: [-122.4194, 37.7749]
            properties:
              name: "San Francisco"
              population: 881549
    paint:
      circle-radius:
        - interpolate
        - ["linear"]
        - ["get", "population"]
        - 500000     # 500,000 people: 8 px
        - 8
        - 5000000    # 5 million: 20 px
        - 20
        - 10000000   # 10 million: 30 px
        - 30
      circle-color: "#3b82f6"
      circle-stroke-width: 2
      circle-stroke-color: "#ffffff"
    interactive:
      hover:
        cursor: pointer
      click:
        popup:
          - h3:
              - property: name
          - p:
              - str: "Population: "
              - property: population
                format: { max-fraction-digits: 0 }   # 8,336,817
controls:
  navigation: true
  scale: true

How it works

Section titled “How it works”

The data is part of the document. The layer’s source: is GeoJSON written under data:, a FeatureCollection with one point per city, so the map needs no other file. For data in a file of its own, give the source a url: instead (Loading data).

bounds: frames the cities. The camera opens on that box (west, south, east, north) whatever the map’s size, so all five cities show on a phone as well as a wide screen. center: and zoom: are still required.

The circle size follows population. interpolate with ["linear"] scales the radius between the stops you list, by the value of ["get", "population"]:

circle-radius:
  - interpolate
  - ["linear"]
  - ["get", "population"]
  - 500000     # 500,000 people: 8 px
  - 8
  - 5000000    # 5 million: 20 px
  - 20
  - 10000000   # 10 million: 30 px
  - 30

A city of 2.7 million (Chicago) falls between the first two stops and gets about 14 px. These are MapLibre expressions, written as YAML lists; Layers & styling explains them.

A click opens a popup. The interactive: block names what the popup shows, and format: writes the population with separators, so New York reads 8,336,817:

interactive:
  hover:
    cursor: pointer
  click:
    popup:
      - h3:
          - property: name
      - p:
          - str: "Population: "
          - property: population
            format: { max-fraction-digits: 0 }   # 8,336,817

Next

Section titled “Next”