geopackage

Go back

Getting Started With GeoPackage

Identifying a GeoPackage

A GeoPackage is an SQLite Database file with a .gpkg extension. If you are unsure whether a file is an SQLite database, you can use a binary or text editor to view the starting bytes of the file and see if they state SQLite format 3.

Opening a GeoPackage

There are a number of ways to open a GeoPackage.

The GeoPackage community tries to maintain a list of operational GeoPackage implementations and this list can be found on the implementations page. Additional information on specific products and versions of products that implement GeoPackage can also be found at http://www.opengeospatial.org/resource/products. You can search by specific versions of the GeoPackage standard. Note: Search for all implementing products.

Creating a GeoPackage

Similarly, if you wish to create a new GeoPackage from scratch or from an existing source file such as a ShapeFile or .csv, below are some suggestions:

Checking a GeoPackage Version

Using a direct SQL interface such as DB Browser is the easiest way to check a GeoPackage version. SQLite uses pragma statements to implement non-standard SQL functions. These statements can be executed just like any other SQL statement and where relevant, they return a result set. The two pragmas you need to know are:

What is in a GeoPackage

Like other relational databases, GeoPackages contain a number of tables. These tables fall into two categories, user-defined data tables and metadata tables. GeoPackages contain two mandatory metadata tables, gpkg_contents and gpkg_spatial_ref_sys. The presence of other metadata tables is dictated by the content being stored (see Content Types). The name of the user-defined data table is the primary key for gpkg_contents and generally is a foreign key for content-specific metadata tables.

gpkg_contents

The gpkg_contents table is the table of contents for a GeoPackage. The mandatory columns in this table are:

gpkg_spatial_ref_sys

For content that has spatial reference (including but not limited to tiles and features), each row in contents must reference a coordinate reference system which is stored in the gpkg_spatial_ref_sys table. The mandatory columns in this table are:

At least three rows must be in this table. There must be one row for each of the following srs_id column values:

However, many more rows that reference other coordinate reference systems (CRSs) are possible. Using CRSs incorrectly is one of the most common ways to break GeoPackage interoperability. When in doubt, discuss CRSs with a geospatial expert to ensure that you are using an appropriate coordinate reference system for your situation.

Content Types

Features

Vector feature data are geographic entities including conceptual ones such as districts, real world objects such as roads and rivers, and observations. (An observation is an act that results in the estimation of the value of a feature property, and involves application of a specified procedure, such as a sensor, instrument, algorithm or process chain. A temperature at a given geographic location provided by a sensor is an example of an observation.) For vector feature data, there is one additional required table: gpkg_geometry_columns. Features are stored in the user-defined data tables identified by the table_name values in gpkg_contents (one table per row).

Figure 1: UML Diagram of Features tables

gpkg_geometry_columns

The gpkg_geometry_columns table describes the geometry for a particular Features table. Each feature table must have a corresponding row in this table. The required columns in this table are:

User-defined Data Tables

Features are stored in user-defined data tables. Each features table has exactly one geometry column, a BLOB. (The structure of this BLOB is described here.) The OGC Simple Features geometry types are the supported geometry types. Other than the geometry column and a primary key, the schema of a features table is up to the implementer. Properties (text, integer, or real) provide additional information about each feature. The GeoPackage standard has an example schema.

Tiles

The GeoPackage Tiles option specifies a mechanism for storing raster data in tile pyramids. “Tile pyramid” refers to the concept of pyramid structure of tiles of different spatial extent and resolution at different zoom levels, and the tile data itself. “Tile” refers to an individual raster image such as a PNG or JPEG that covers a specific geographic area. “Tile matrix” refers to rows and columns of tiles that all have the same spatial extent and resolution at a particular zoom level. “Tile matrix set” refers to the definition of a tile pyramid’s tiling structure. This mechanism is based on the model for tile matrix sets described in Section 6 of the WMTS Implementation Specification.

If tiles are to be included in a GeoPackage, there are two additional required metadata tables, gpkg_tile_matrix_set and gpkg_tile_matrix. In addition to these tables, each tile pyramid requires a user-defined table that contains the actual tiles.

Figure 2: UML Diagram of Tiles tables

gpkg_tile_matrix_set

The gpkg_tile_matrix_set table describes names a tile matrix set (pyramid). The columns in this table are:

gpkg_tile_matrix

Each tile matrix set is composed of one or more tile matrices, each identified by its zoom level. The required columns in this table are:

By default, zoom levels are separated by powers of two, but if this is inappropriate for your scenario, other multiples are possible by using the Zoom Other Levels extension.

User Data Tables

The physical tiles (data) are stored in user data tables with a specific schema. The required columns for these tables are:

Unless you use an extension, PNG and JPG are the two supported file types for the tiles. PNG is generally better for synthetic data (i.e., digital maps) because it is lossless and its compression codec compresses synthetic data fairly well. JPG is generally better for natural data (i.e., satellite or aerial imagery) due to its superior (though lossy) compression. However, since PNG supports alpha transparency and JPG does not, it is common to use PNG tiles around the boundary of a tile pyramid. This allows users to see the data underneath the tile boundaries. JPG files have an adjustable compression rating. We have found that a ratings in the range 50-75 (out of 100) work best for imagery. Ratings that are too high use too much space and ratings that are too low have too many visible artifacts. Within the 50-75 range it is a reasonable tradeoff between file size and image quality.

Tile pyramids may be sparsely populated. This is a good way to manage GeoPackage size. Applications should be aware of this possibility and if possible, drop to the next zoom level to render that part of the map.

Attributes

Attributes are tables that only contain non-spatial data. The rules for attributes are similar to those for features, but attributes have no geometry column and the corresponding row in gpkg_contents has a data_type of “attributes”. This data is commonly joined with spatial data as required by an application.

Extensions

In addition to tiles, features, and attributes, GeoPackage has a well-defined extension mechanism to support use cases that are not part of the core standard. A GeoPackage extension is a set of one or more requirements clauses that either profiles / extends existing requirements clauses in the GeoPackage standard or adds new requirements clauses. Existing requirement clause extension examples include additional geometry types, additional SQL geometry functions, and additional tile image formats. New requirement clause extension examples include spatial indexes, triggers, additional tables, other BLOB column encodings, and other SQL functions.

Files that use one or more extensions are by definition Extended GeoPackages. There are two categories of extensions, registered and community.

gpkg_extensions

The extensions table describes the extensions that are in use in a GeoPackage. The columns for this table are:

Registered Extensions

Registered extensions have been reviewed and adopted by OGC and are for all intents and purposes part of the standard. Most registered extensions are published as part of the core standard but they may be published independently as well.

The following extensions have been adopted by OGC:

Community Extensions

OGC acknowledges that there are use cases not covered by the GeoPackage standard. Implementers are welcome to use the extension mechanism defined here to develop community extensions. The extension mechanism provides advantages including discoverability (the extensions in use can be discovered by scanning a single table) and uniformity (declaring that an extension is in use indicates that a defined set of requirements are being met). However, this is a decision that should be made carefully as custom extensions do introduce interoperability risks. OGC manages a registry of community extensions.

OGC is unable to endorse community extensions. Therefore an Extended GeoPackage containing community extensions will not pass conformance tests. However, a community of interest MAY waive that requirement in its own GeoPackage profile, with the caveat that it must bear the responsibility of endorsing the new extension(s).

Implementers that are interested in developing their own extensions are encouraged to contact OGC to ensure that the extensions are developed in accordance with OGC policies and in a way that minimizes risks to interoperability. OGC will consider adopting externally developed extensions that address a clear use case, have a sound technical approach, and have a commitment to implementation by multiple implementers.