Skip to main content
A GeoPackage (.gpkg) is a single SQLite database file that can hold multiple types of geospatial data together. Because it is built on SQLite, any tool that can open a SQLite database can read the raw tables inside — but the OGC GeoPackage standard defines exactly which tables must exist and how the data must be structured, so interoperability across tools is guaranteed.

​
What a GeoPackage contains

Features

Vector geometries (points, lines, polygons) paired with attribute columns. Each feature table is analogous to a GIS layer.

Tiles

Pre-rendered raster tiles organized by zoom level and tile coordinate. Suitable for basemaps and image overlays.

Attributes

Non-spatial tabular data — like lookup tables or metadata records — stored without any geometry column.

​
The gpkg_contents table

Every user table in a GeoPackage — whether it stores features, tiles, or attributes — is registered in the gpkg_contents metadata table. A row in gpkg_contents records:
  • table_name — the name of the user data table
  • data_type — one of features, tiles, or attributes
  • identifier and description — human-readable labels
  • min_x, min_y, max_x, max_y — the bounding box of the content
  • srs_id — foreign key to the spatial reference system
The library exposes this through ContentsDataType, which maps type name strings to the FEATURES, TILES, and ATTRIBUTES enum values.

​
Spatial reference systems

Every feature table and tile table is linked to a spatial reference system (SRS) recorded in gpkg_spatial_ref_sys. The SRS defines the coordinate space (e.g., WGS 84 / EPSG:4326 or Web Mercator / EPSG:3857). The SpatialReferenceSystemDao class provides access to this table, and the CRS WKT Extension can store the full WKT representation of the SRS.

​
Opening and creating GeoPackages

Use GeoPackageManager — the top-level entry point — to open an existing file or create a new one. 
import { GeoPackageAPI } from '@ngageoint/geopackage';

// Open an existing GeoPackage (read-only by default)
const geoPackage = await GeoPackageAPI.open('/path/to/file.gpkg');

// Create a new GeoPackage
const newGeoPackage = await GeoPackageAPI.create('/path/to/new.gpkg');
Both methods return a GeoPackage instance. That object exposes every DAO, extension, and utility method the library provides.
Always close the GeoPackage when you are done to release the underlying SQLite connection: geoPackage.close().

​
Inspecting a GeoPackage

Once you have a GeoPackage instance you can list its contents: 
import { GeoPackageAPI } from '@ngageoint/geopackage';

const geoPackage = await GeoPackageAPI.open('/path/to/file.gpkg');

// List feature table names
const featureTables = geoPackage.getFeatureTables();
console.log('Feature tables:', featureTables);

// List tile table names
const tileTables = geoPackage.getTileTables();
console.log('Tile tables:', tileTables);

// List attribute table names
const attributeTables = geoPackage.getAttributesTables();
console.log('Attribute tables:', attributeTables);

geoPackage.close();

​
File portability

Because a GeoPackage is a single file, it is easy to share, copy, and version. There are no sidecar files, no directories of tiles, and no external databases. Any application that implements the OGC spec can open the same .gpkg file — including QGIS, ArcGIS, GDAL, and mobile SDKs.

Build docs developers (and LLMs) love

Get started for freeTalk to us