GIS item JSON

  • Updated On Apr 8, 2025
  • Published on Jan 1, 2025
Prev Next

Overview

The GIS Item JSON structure in Dataloop provides a comprehensive format that encapsulates all necessary data and metadata for each annotated entity within the system. This structure is designed to represent an 'Item' — a core data unit in Dataloop's platform — and its associated information for annotation purposes. Here’s a breakdown based on the provided content:

JSON Structure

Each data entity in Dataloop’s system has a dedicated JSON format that encapsulates the item’s data and metadata, enabling efficient tracking, access, and management within the platform. This JSON file is essential for exporting or downloading item annotations and can be accessed for detailed inspection or integration purposes.

GIS Item JSON Formats

Type: XYZ

XYZ is a tiled web map format that loads map tiles dynamically from a specified URL using the {z}/{x}/{y} pattern. It is commonly used for raster-based layers like OpenStreetMap (OSM) and supports zoom levels for smooth navigation. Optional layers (XYZ, OSM, COG) can be added for enhanced visualization.


{
    "shebang": "dataloop",                      //For the type of Web Map Item, it should be dataloop only and mandatory
    "metadata": {
        "dltype": "gis"                         //For the type of Web Map Item, it should be gis only and mandatory
    },
    "layer": {                                  // Representing the Tile Layer - it's a mandatory layer object
        "name": "XYZ Image",                    // User-defined name for the GIS item
        "type": "xyz",                          // Currently supporting "xyz", "osm" and "cog" types only
        "url": "https://dummy-tile.com/surveys/1723928/tiles/{z}/{x}/{y}?auth_token=fM68PVOJO8p5m2sPo4Cqdcoi4sLSsecR&datatype_name=vexcel_urban_vertical_jpg"
    },
    "optionalLayers":                           // Representing the Optional Layers array, which can have multiple layers("xyz", "osm" and "cog")
    [ 
        {
            "name": "OpenStreetMap",            // Name of the optional layer (OpenStreetMap in this case).
            "type": "osm",                      // Specifies that this optional layer is an OpenStreetMap (OSM) layer.
            "url": "",                          // URL for the optional layer (empty in this case, meaning default OSM tiles may be used).                      
            "ref": "<item_id>"                  // Reference to the item ID associated with this optional layer.
	},
        }
    ],
    "zoom":20,                                  // It's an optional zoom level, which can be between 0 to 28
    "minZoom":0,                                // It's an optional min zoom level, which can be between 0 to 28
    "maxZoom":30,                               // It's an optional max zoom level, which can be between 1 to 28
    "epsg":"4326",                              // Representing the file's Coordinate System . (3857, 3035, 4326)
    "bounds": [                                 // The coordinates that represents the (square) area within the map that the user can view, and should add/edit the annotations. I.e. the bounds where the projection is valid. Optional field.
        [-118.33559370040894, 33.82662439264756],//top left
        [-118.33497619628906, 33.82610016009953]//bottom    right
    ],
    "aoi": [                                    // Coordinates representing the Area of Interest -- The areas within the bounds of the tile layer, where I allow to create annotations. I.e. the “boarders of the canvas”. Optional field. 
        [-118.33545684814453, 33.826504880358854],
        [-118.33545684814453, 33.82621967238824],
        [-118.33511352539062, 33.82621967238824],
        [-118.33511352539062, 33.826504880358854],
        [-118.33545684814453, 33.826504880358854]
    ]
}

Field Definitions

Key Name Definition Parent Key
shebang A fixed identifier indicating that the data structure is in Dataloop's format. N/A
metadata Stores additional metadata about the Web Map Item. N/A
dltype For the type of Web Map Item, it should be gis only and mandatory metadata
layer Representing the Tile Layer - it's a mandatory layer object N/A
name Name of the base map layer. layer
type Defines the tile layer type. layer
url URL template for the tile source. layer
optionalLayers Array of additional tile layers that can be used alongside the base layer. N/A
name Name of the optional map layer optionalLayers
type Type of the optional layer ("xyz", "osm", "cog") optionalLayers
url URL for the tile source optionalLayers
zoom Defines the initial zoom level of the map. N/A
minZoom Defines the minimum zoom level allowed. N/A
maxZoom Defines the maximum zoom level allowed. N/A
epsg Specifies the Coordinate Reference System (CRS). 4326 → WGS 84 (Latitude/Longitude), 3857 → Web Mercator, and 3035 → Lambert Azimuthal Equal-Area. N/A
bounds Defines the bounding box that limits the map area where users can view or edit annotations. First value: [longitude, latitude] (Top-left corner), and Second value: [longitude, latitude] (Bottom-right corner) N/A
aoi Defines the Area of Interest (AOI), which is the section of the map where annotations are allowed. I.e. the “boarders of the canvas”. Optional field. N/A

Type: geoTiff

GeoTIFF is a raster-based GIS format that stores geospatial metadata, making it ideal for geo-referenced imagery such as satellite images and aerial photography. It can be accessed via a URL or item ID and supports different projections (EPSG: 3035, 4326, 3857) with optional overlays like OpenStreetMap for better visualization.

{
    "shebang": "dataloop",                      //For the type of Web Map Item, it should be dataloop only and mandatory
	"metadata": {
        "dltype": "gis"                         //For the type of Web Map Item, it should be gis only and mandatory
    },
    "layer": {  
        "name": "GeoTIFF Image",  // User-defined name for the main GIS layer.
        "type": "geoTiff",  // Specifies the layer type. Options: "geoTiff" (raster-based GIS format), "xyz", "osm".
        "ref": "67d14487f561d469323d8996"  // Reference ID for the GIS item stored in Dataloop. ** It can be either `ref` or `url`.
    },
    "optionalLayers": [  
        {
            "name": "OpenStreetMap",  // Name of the optional overlay layer.
            "type": "osm",  // Type of the optional layer. Can be "osm", "xyz", or "cog".
            "url": ""  // URL source for the optional layer (empty means default OSM tiles will be used).
        }
    ],
    "epsg": "4326",  // Representing the file's Coordinate System (EPSG). Currently we only support epsg 4326 (WGS84).
    "bounds": [  
        [5.046927, 51.9243133],  // Top-left coordinate of the bounding box (longitude, latitude).
        [5.126927, 51.8243163]   // Bottom-right coordinate of the bounding box (longitude, latitude). Defines the visible area where annotations can be created.
    ],
    "aoi": [  
        [5.096927, 51.8843133],  // First coordinate of the Area of Interest (AOI).
        [5.076927, 51.8843133],  // Second coordinate of the AOI polygon.
        [5.076927, 51.8643163],  // Third coordinate of the AOI polygon.
        [5.096927, 51.8643163],  // Fourth coordinate of the AOI polygon.
        [5.096927, 51.8843133]   // Closing coordinate (same as the first), forming a closed polygon. Defines the area where annotations are allowed.
    ]
}

Note: The url or ref must be provided.

Field Definitions

Key Name Definition Parent Key
shebang Identifier indicating the system or format used, in this case, Dataloop. Root
metadata Contains metadata about the GIS file. Root
dltype Defines the dataset type as GIS, useful for categorization. metadata
layer Defines the primary GIS layer details. Root
name Name of the GIS layer (e.g., TIFF). layer
type Specifies that this layer is of type GeoTIFF. layer
url URL to fetch the GIS layer data. layer
ref Reference to the item ID associated with this layer. layer
optionalLayers List of additional optional layers. Root
name Name of the optional layer (e.g., OpenStreetMap). optionalLayers
type Type of the optional layer (e.g., osm for OpenStreetMap). optionalLayers
url URL for the optional layer (empty in this case). optionalLayers
epsg Specifies the coordinate system Root
bounds Coordinates defining the viewable/editable area of the map. Root
aoi Coordinates representing the Area of Interest for annotations. Root

Note: Using either url or ref is optional.

Coordinate system and projection

Users can modify the map coordinate system and projection within the app.

  • Coordinate System: Defines locations using numerical values.
  • Geographic Coordinate System (GCS): Uses latitude and longitude (e.g., WGS 84 / EPSG:4326).
  • Projection: Converts the Earth's curved surface into a flat map, causing some distortions.
    • Mercator – Preserves shape, distorts area.
    • Albers Equal-Area – Preserves area, distorts shape.
    • UTM – Minimizes distortion for small areas.