NetBox GeoView

NetBox GeoView is a NetBox plugin for displaying infrastructure in a map-oriented view.

It provides:

• a Leaflet map with configurable raster tile layers
• filters for sites, devices, tags, ownership, tenancy, and related objects
• configurable site and device popups, including custom fields
• direct-distance measurement and optional Valhalla route calculation
• reusable development test data for sites, locations, device types, devices, and custom fields

Versioning

The plugin uses Semantic Versioning in the format MAJOR.MINOR.PATCH.

• MAJOR: incompatible plugin changes
• MINOR: new backward-compatible features
• PATCH: bug fixes and small corrections

NetBox compatibility is managed separately through min_version and max_version in the plugin.

Project Note

This is a personal project to see how far one can go with a practical NetBox plugin idea.

Most of the code was generated with Codex as a coding co-pilot, but maintenance responsibility stays with the developer (the human still carries the pager).

Compatibility

Installation

Install inside the NetBox virtual environment:

pip install netbox-geoview

Optional: install directly from a tagged GitHub source archive:

pip install https://github.com/phlpr/netbox_geoview/archive/refs/tags/v0.6.0.tar.gz

Configuration

Example plugin settings for configuration.py:

PLUGINS = ["netbox_geoview"]

PLUGINS_CONFIG = {
    "netbox_geoview": {
        "start_latitude": 47.59397,
        "start_longitude": 14.12456,
        "start_zoom": 7,
        "min_zoom": 2,
        "max_zoom": 19,
        "valhalla_url": "https://valhalla1.openstreetmap.de/route",
        "valhalla_timeout": 10,
        "valhalla_costing_options": ["auto", "bicycle", "pedestrian"],
        "valhalla_default_costing": "auto",
        "valhalla_request_defaults": {
            "alternates": 1,
            "directions_options": {
                "units": "kilometers",
            },
        },
        "valhalla_headers": {
            "X-Client-Id": "your-company-netbox-geoview",
        },
        "valhalla_query": {},
        "default_tile_layer": "OpenStreetMap",
        "scroll_wheel_zoom": True,
        "site_marker": {
            "color": "#f1c40f",
            "symbol": "",
            "icon_url": "",
            "icon_size": [28, 40],
            "icon_anchor": [14, 40],
            "popup_anchor": [0, -34],
        },
        "site_group_markers": {
            "burgenland": {"color": "#f1c40f"},
            "karnten": {"color": "#e74c3c"},
            "niederosterreich": {"color": "#3498db"},
            "oberosterreich": {"color": "#2ecc71"},
            "salzburg": {"color": "#ff69b4"},
            "steiermark": {"color": "#16a085"},
            "tirol": {"color": "#9b59b6"},
            "vorarlberg": {"color": "#34495e"},
            "wien": {"color": "#f39c12"},
        },
        "tile_layers": [
            {
                "name": "OpenStreetMap",
                "url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
                "attribution": "© OpenStreetMap contributors",
            },
            {
                "name": "OpenStreetMap DE",
                "url": "https://tile.openstreetmap.de/{z}/{x}/{y}.png",
                "attribution": "© OpenStreetMap contributors",
            },
            {
                "name": "OpenStreetMap HOT",
                "url": "https://a.tile.openstreetmap.fr/hot/{z}/{x}/{y}.png",
                "attribution": "© OpenStreetMap contributors, Humanitarian OpenStreetMap Team",
            },
            {
                "name": "MapTiler Satellite",
                "url": "https://api.maptiler.com/maps/satellite/{z}/{x}/{y}.jpg",
                "attribution": "© MapTiler",
                "query": {
                    "key": "YOUR_MAPTILER_API_KEY",
                },
            },
            {
                "name": "MapTiler Hybrid",
                "url": "https://api.maptiler.com/maps/hybrid/{z}/{x}/{y}.png",
                "attribution": "© MapTiler",
                "query": {
                    "key": "YOUR_MAPTILER_API_KEY",
                },
            },
        ],
        "tile_provider_url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
    }
}

The same example is included in configuration.example.py.

Available settings:

• start_latitude: initial map latitude
• start_longitude: initial map longitude
• start_zoom: initial map zoom level
• min_zoom: minimum allowed zoom level
• max_zoom: maximum allowed zoom level
• valhalla_url: base URL of the Valhalla route endpoint
• valhalla_timeout: timeout in seconds for route requests
• valhalla_costing_options: route profile options shown in UI
• valhalla_default_costing: default route profile
• valhalla_request_defaults: additional request payload defaults
• valhalla_headers: optional HTTP headers for Valhalla requests
• valhalla_query: optional query string parameters for Valhalla requests
• default_tile_layer: default base layer name or ID
• scroll_wheel_zoom: enables zooming with the mouse wheel
• site_marker: default marker appearance for selected sites
• site_group_markers: marker overrides by site group name or slug
• tile_layers: list of available base layers
• query: optional query string parameters per layer, useful for API keys
• headers: optional HTTP headers per layer
• tile_provider_url: upstream tile URL template with {z}, {x}, and {y}

Satellite Providers

Providers with official API-key-based access that fit this plugin well:

• MapTiler Satellite: simple raster tile API with API key in the request. Official docs: MapTiler Cloud API
• MapTiler Hybrid: raster hybrid style with satellite imagery plus labels and borders, also usable with an API key. Inference from MapTiler's documented style family plus verified tile endpoint.
• Mapbox Satellite: raster tiles with access token authentication. Official docs: Mapbox Tilesets Reference
• Esri World Imagery: enterprise-capable imagery via ArcGIS location services and token-based authentication. Official docs: ArcGIS service endpoints and Esri Leaflet basemap example

Recommendation:

• MapTiler Satellite is the easiest fit for the current plugin because it follows a straightforward raster tile pattern with an API key.
• Mapbox Satellite also fits well and can be configured today with query.access_token.
• Esri World Imagery is a strong enterprise option, but its exact request pattern depends on the ArcGIS endpoint and token model you want to use.

Requirements

• NetBox 4.5.4 through 4.6.x; release 0.6.0 is tested with NetBox 4.6.8
• Python >=3.12
• No additional Python runtime dependencies are required beyond NetBox's own environment
• Installation in the NetBox virtual environment (for example: pip install <path-to-plugin>)
• Plugin activation in configuration.py:
  • PLUGINS = ["netbox_geoview"]
  • PLUGINS_CONFIG = {"netbox_geoview": {...}}
• For MapTiler layers: valid API key (query.key)
• Optional for routing: reachable Valhalla endpoint (valhalla_url)

Development Test Data

Release 0.6.0 includes an idempotent management command that creates a reusable development data set:

python manage.py seed_geoview_testdata

The command is intended only for development and test databases. It creates or updates clearly prefixed sites, locations, device types, devices, roles, and custom fields. See TESTDATA.md for details and for using a custom JSON definition.

Firewall / Network Allowlist

NetBox GeoView fetches external map and route data server-side. So the egress rules must be applied on the NetBox host (or its outbound proxy), not only on client browsers.

Required for default tile setup:

• HTTPS/443 to tile.openstreetmap.org
• HTTPS/443 to tile.openstreetmap.de
• HTTPS/443 to a.tile.openstreetmap.fr

Required when using MapTiler layers:

• HTTPS/443 to api.maptiler.com

Optional when routing is enabled (Valhalla):

• HTTPS/443 to your configured Valhalla host from valhalla_url
• For the shipped example: HTTPS/443 to valhalla1.openstreetmap.de

Valhalla itself is MIT-licensed and can be self-hosted commercially. The example endpoint is a public demonstration service, not an enterprise service: fair-use limits apply and no availability guarantee is provided. Applications using that endpoint should send an identifying X-Client-Id header. For production or high-volume use, self-host Valhalla or use a provider with an appropriate SLA.

The default map and routing data is based on OpenStreetMap. Keep the visible © OpenStreetMap contributors attribution and comply with the ODbL when using or redistributing derived data.

If your environment uses an explicit outbound proxy, make sure NetBox can reach these hosts through that proxy and that TLS inspection does not break certificate validation.