# Map Layers

Use this guide to choose a tileset, configure its source layers and zoom range, and find the attributes and styling resources for your map.

## Choose a tileset

Tilesets are unstyled [Mapbox Vector Tile](https://github.com/mapbox/vector-tile-spec) protobuf data. Configure a vector source with this URL template:

```text
https://api.psma.com.au/v1/maps/geoscape_v1/{tileset}/{z}/{x}/{y}.pbf
```

- `z`: zoom level
- `x`: tile column in XYZ coordinates
- `y`: tile row in XYZ coordinates

Use the source-layer name in your map style. A tileset can contain more than one source layer.

| Tileset | Source layers | Published zoom range |
| --- | --- | --- |
| `gnaf` | `gnaf` | 0–15 |
| `localities` | `localities` | 0–14 |
| `postcodes` | `postcode_polygons`, `postcode_points` | 0–12 |
| `local_government_areas` | `local_government_areas` | 0–12 |
| `wards` | `wards` | 0–14 |
| `buildings` | `buildings` | 0–15 |
| `solar` | `solar` | 0–17 |
| `cadastre` | `cadastre` | 0–16 |
| `property` | `property` | 0–16 |
| `electoral` | `state`, `commonwealth` | 0–13 |
| `country` | `country` | 0–14 |
| `state` | `state` | 0–14 |
| `airports_polygon` | `airport` | 0–14 |
| `rail` | `railway_line`, `railway_station` | 0–14 |

## Tile attributes

The following field names and example values come from the published reference. Use metadata to check the fields in the current tileset. Example IDs and dates are illustrative, not lookup guarantees.

### G-NAF

- `ADDRESS_DETAIL_PID`: `GANT_703831523`
- `ALIAS_PRINCIPAL`: `PRINCIPAL`
- `GEOCODE_TYPE`: `PROPERTY_CENTROID`
- `PRIMARY_SECONDARY`: primary or secondary address classification
- `street_number`: `60`

### Localities

- `locality_pid`
- `locality_polygon_pid`
- `locality_name`: `DARWIN`
- `area`: square kilometres (km²)

### Postcodes

#### `postcode_polygons`

- `postcode_pid`: `NSW216111`
- `postcode_polygon_pid`: `161`
- `postcode`: `2161`

#### `postcode_points`

- `postcode_pid`: `NSW216111`
- `postcode_point_pid`: `161`
- `postcode`: `2161`

### Local Government Areas

- `lga_pid`: `lga744170e79f38`
- `lga_polygon_pid`: `lgp5b4307df2e0f`
- `lga_name`: `Darwin Municipality`
- `area`: `139.894` km²

### Wards

- `ward_pid`: `wadff86c1934cd4`
- `ward_polygon_pid`: `wdp3faBuVCopmPP`
- `ward_name`: `Ararat Rural City`
- `state`: `VIC`
- `date_created`: `2023-08-15`

### Buildings

- `building_pid`: `blda54bc84c09be`

### Solar

- `capture_date`: `2023-08-25`
- `capture_source`: `7.5cm aerial`
- `solar_area`: `25.62` m²
- `solar_building_pid`: `sbp7e895616ffe4`
- `solar_type`: `Polycrystalline`
- `solar_pid`: `sol1YfOR2d2h8iP`

### Cadastre

- `cadastre_pid`: `cad0941c65bd1cd`
- `cadastre_polygon_pid`: `cp1923530d6ca02`
- `parcel_type`: `Lot`
- `area`: `2020.48` m²
- `base_parcel`: `Yes`

### Property

- `property_pid`: `prpf45bf15a0428`
- `property_polygon_pid`: `pp0cb2086a6829f`
- `base_property`: `Yes`
- `area`: `405630.9` m²

### Electoral Boundaries

#### Commonwealth attributes

- `commonwealth_electoral_name`: `MALLEE`
- `commonwealth_electoral_pid`: `VIC2`
- `commonwealth_electoral_polygon_pid`: `11914`
- `date_created`: `2018-08-01`
- `date_gazetted`: `2021-07-26`
- `date_retired`: `null`
- `redistribution_year`: `2021`

#### State attributes

- `date_created`: `2015-05-05`
- `date_retired`: `null`
- `effective_end_date`: `2022-10-31`
- `effective_start_date`: `2014-11-29`
- `state_electoral_class_name`: `Legislative Assembly`
- `state_electoral_name`: `LOWAN`
- `state_electoral_pid`: `VIC197`
- `state_electoral_polygon_pid`: `992`

### Country

- `country_abbreviated`: `AUS`
- `country_name`: `Australia`
- `country_pid`: `1`
- `country_polygon_pid`: `1`

### States

- `state_pid`
- `state_polygon_pid`
- `state_name`: `Australian Capital Territory`
- `state_abbreviation`: `ACT`

### Airports

- `airport_pid`
- `airport_polygon_pid`
- `airport_name`

### Rail

#### Railway Line attributes

- `date_created`: `2019-05-03`
- `ground_relationship`: `On Ground`
- `guage_type`: `STANDARD BROAD`
- `jurisdiction_id`: `10066414`
- `operational_status`: `Operational`
- `railway_line_pid`: `VIC16652773`
- `railway_name`: `ALBION-BROADMEADOWS`
- `railway_pid`: `VIC5149`
- `transport_hierarchy`: `Railway Line 1`

#### Railway Station attributes

- `date_created`: `2019-04-17`
- `jurisdiction_id`: `5580490`
- `operational_status`: `Operational`
- `railway_station_name`: `SOUTH KENSINGTON STATION`
- `railway_station_pid`: `VIC16208061`
- `transport_hierarchy`: `Railway Station`

## Zoom and detail

Set the source's `maxzoom` to its published maximum. Let the map client overzoom that source when displaying higher zooms.

Low-zoom tiles simplify geometry and can omit small features. Use tiles for visualisation. Retrieve authoritative feature attributes and geometries through the relevant data API when performing analysis. The [Rail product guide](https://docs.geoscape.com.au/en/stable/rail.html) explains rail attributes.

## Read tileset metadata

`/v1/maps/index.json` returns an array of [TileJSON 3.0.0](https://github.com/mapbox/tilejson-spec/tree/master/3.0.0) objects:

- `tiles` supplies tile URL templates
- `vector_layers[].id` is the source-layer name
- `vector_layers[].fields` maps attribute names to type descriptions
- `vector_layers[].geometry` describes the geometry type
- `minzoom` and `maxzoom`, when supplied within a vector layer, describe available zooms
- `bounds` uses west,south,east,north longitude and latitude degrees
- `center` uses longitude,latitude,zoom

Metadata and examples can change as datasets are updated. Inspect the metadata for the deployed data. Authenticate every tile request, including those made from metadata templates.

## Styling resources

The `geoscape-light` stylesheet follows the [Mapbox Style Specification](https://docs.mapbox.com/style-spec/). Authenticate the style and its tile and font requests.

Useful clients and tools include:

- [MapLibre](https://maplibre.org/) and [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/)
- [Leaflet](https://leafletjs.com/) and [OpenLayers](https://openlayers.org/), with compatible vector-tile support
- [Maputnik](https://maputnik.github.io/) and [Fresco](https://github.com/go-spatial/fresco) for style editing
- [Protocol Buffers](https://protobuf.dev/) for the binary encoding

The TileJSON specification is licensed under [CC BY 3.0 US](https://creativecommons.org/licenses/by/3.0/us/).

## Attribution and G-NAF use

Retain attribution when displaying Geoscape data. G-NAF use is also subject to its licensing and privacy requirements. Review the [G-NAF overview](https://geoscape.com.au/data/g-naf/), [G-NAF dataset and licence](https://data.gov.au/data/dataset/geocoded-national-address-file-g-naf), and [Australian Privacy Principles](https://www.oaic.gov.au/privacy-law/privacy-act/australian-privacy-principles).

Review the [G-NAF end-user licence](https://data.gov.au/data/dataset/19432f89-dc3a-4ef3-b943-5326ef1dbecc/resource/09f74802-08b1-4214-a6ea-3591b2753d30/download/20160226-eula-open-g-naf.pdf) and [additional G-NAF use restrictions](https://data.gov.au/data/dataset/19432f89-dc3a-4ef3-b943-5326ef1dbecc/resource/9a8f6baa-f790-49a0-84b1-3cb39a6a1b88/download/fact-sheet-open-g-naf-use-restriction.pdf).

## Next steps

- [Build a map](/guides/maps/getting-started)
- [Review attribution requirements](/guides/attribution)