openswmm_geopackage.h File Reference

OpenSWMM Engine — GeoPackage C API. More...

#include "openswmm_engine_export.h"

Include dependency graph for openswmm_geopackage.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	SWMM_GPKG_OK   0
#define	SWMM_GPKG_ERR   -1

Typedefs
typedef void *	SWMM_Gpkg
	Opaque handle to an open GeoPackage database.

Functions
SWMM_ENGINE_API SWMM_Gpkg	swmm_gpkg_open (const char *path)
	Open an existing GeoPackage file.
SWMM_ENGINE_API void	swmm_gpkg_close (SWMM_Gpkg gpkg)
	Close the GeoPackage and free all resources.
SWMM_ENGINE_API const char *	swmm_gpkg_last_error (SWMM_Gpkg gpkg)
	Get the last error message.
SWMM_ENGINE_API int	swmm_gpkg_begin (SWMM_Gpkg gpkg)
	Begin a transaction for bulk operations.
SWMM_ENGINE_API int	swmm_gpkg_commit (SWMM_Gpkg gpkg)
	Commit the current transaction.
SWMM_ENGINE_API int	swmm_gpkg_rollback (SWMM_Gpkg gpkg)
	Roll back the current transaction.
SWMM_ENGINE_API int	swmm_gpkg_register (const char *license_key, const char *organization, const char *contact_email, const char *deployment_id)
	Register the GeoPackage plugin.
SWMM_ENGINE_API int	swmm_gpkg_is_registered (void)
	Check whether the GeoPackage plugin is registered.
SWMM_ENGINE_API int	swmm_gpkg_simulation_count (SWMM_Gpkg gpkg)
	Get the number of simulation runs in the GeoPackage.
SWMM_ENGINE_API int	swmm_gpkg_simulation_id (SWMM_Gpkg gpkg, int index, char *buf, int bufsz)
	Get the simulation_id at the given index.
SWMM_ENGINE_API int	swmm_gpkg_node_count (SWMM_Gpkg gpkg, const char *simulation_id)
SWMM_ENGINE_API int	swmm_gpkg_link_count (SWMM_Gpkg gpkg, const char *simulation_id)
SWMM_ENGINE_API int	swmm_gpkg_subcatch_count (SWMM_Gpkg gpkg, const char *simulation_id)
SWMM_ENGINE_API int	swmm_gpkg_gage_count (SWMM_Gpkg gpkg, const char *simulation_id)
SWMM_ENGINE_API int	swmm_gpkg_topology_edge_count (SWMM_Gpkg gpkg, const char *simulation_id)
SWMM_ENGINE_API int	swmm_gpkg_variable_count (SWMM_Gpkg gpkg)
SWMM_ENGINE_API int	swmm_gpkg_read_result_ts (SWMM_Gpkg gpkg, const char *simulation_id, const char *object_type, const char *object_id, const char *variable_name, double *times, double *values, int max_count)
	Read a result timeseries for one object and variable.
SWMM_ENGINE_API int	swmm_gpkg_result_ts_count (SWMM_Gpkg gpkg, const char *simulation_id, const char *object_type, const char *object_id, const char *variable_name)
	Get the number of result timeseries records for a query.
SWMM_ENGINE_API int	swmm_gpkg_read_summary (SWMM_Gpkg gpkg, const char *simulation_id, const char *object_type, const char *object_id, const char *variable_name, double *value)
	Read a single summary statistic value.
SWMM_ENGINE_API int	swmm_gpkg_create_observed_series (SWMM_Gpkg gpkg, const char *name, const char *variable_name, const char *object_type, const char *object_id, const char *source, const char *units)
	Create an observed data series.
SWMM_ENGINE_API int	swmm_gpkg_write_observed_value (SWMM_Gpkg gpkg, int series_id, const char *timestamp, double value, const char *quality_flag)
	Write a single observed data point.
SWMM_ENGINE_API int	swmm_gpkg_write_observed_values (SWMM_Gpkg gpkg, int series_id, const char **timestamps, const double *values, const char **quality_flags, int count)
	Bulk-write a vector of observed data points to a series.
SWMM_ENGINE_API int	swmm_gpkg_observed_series_count (SWMM_Gpkg gpkg)
	Get the number of observed series in the GeoPackage.
SWMM_ENGINE_API int	swmm_gpkg_observed_value_count (SWMM_Gpkg gpkg, int series_id)
	Get the number of values in an observed series.
SWMM_ENGINE_API int	swmm_gpkg_read_observed_values (SWMM_Gpkg gpkg, int series_id, char *timestamps, int ts_buf_len, double *values, int max_count)
	Read observed timeseries values into caller-supplied arrays.
SWMM_ENGINE_API int	swmm_gpkg_query_int (SWMM_Gpkg gpkg, const char *sql)
	Execute a read-only SQL query and get the first integer result.
SWMM_ENGINE_API int	swmm_gpkg_query_double (SWMM_Gpkg gpkg, const char *sql, double *result)
	Execute a read-only SQL query and get the first double result.

Detailed Description

OpenSWMM Engine — GeoPackage C API.

Provides a C89-compatible API for interacting with GeoPackage files produced by the OpenSWMM engine. The API has two modes:

Read-only access to model definitions, simulation results, and summary statistics. These are written by the engine's plugin system (GeoPackageInputPlugin, GeoPackageOutputPlugin, GeoPackageReportPlugin) and are not modifiable through this C API.

Read-write access to observed / sensor timeseries data. This API is designed for calibration and comparison workflows: import measured data from external sources, associate it with model objects, and query it alongside simulation results.

Transactions are available for bulk operations. Wrapping observed data imports in a transaction (swmm_gpkg_begin / swmm_gpkg_commit) can improve insert performance by 10-100x.

This header is only available when compiled with OPENSWMM_WITH_GEOPACKAGE=ON. Link against openswmm_geopackage.

Usage:

#include <openswmm/engine/openswmm_geopackage.h>
 
SWMM_Gpkg gpkg = swmm_gpkg_open("model.gpkg");
 
// Read model metadata
int nn = swmm_gpkg_node_count(gpkg, "run_1");
 
// Read simulation results
double values[100];
double times[100];
int n = swmm_gpkg_read_result_ts(gpkg, "run_1", "NODE", "J1",
                                  "depth", times, values, 100);
 
// Import observed data (in a transaction for speed)
swmm_gpkg_begin(gpkg);
int sid = swmm_gpkg_create_observed_series(gpkg, "USGS_flow",
             "flow", "LINK", "C1", "USGS", "CMS");
double ts_vals[] = {1.5, 2.3, 1.8};
const char* ts_times[] = {"2026-01-15T08:00:00Z",
                           "2026-01-15T09:00:00Z",
                           "2026-01-15T10:00:00Z"};
swmm_gpkg_write_observed_values(gpkg, sid, ts_times, ts_vals, NULL, 3);
swmm_gpkg_commit(gpkg);
 
swmm_gpkg_close(gpkg);

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright

Copyright (c) 2026 Caleb Buahin. All rights reserved.

License\n MIT License

Macro Definition Documentation

SWMM_GPKG_ERR

#define SWMM_GPKG_ERR   -1

General error (call swmm_gpkg_last_error).

SWMM_GPKG_OK

#define SWMM_GPKG_OK   0

Success.

Typedef Documentation

SWMM_Gpkg

typedef void* SWMM_Gpkg

Opaque handle to an open GeoPackage database.

Function Documentation

swmm_gpkg_begin()

SWMM_ENGINE_API int swmm_gpkg_begin

(

SWMM_Gpkg

gpkg

)

Begin a transaction for bulk operations.

Wrapping multiple observed data inserts in a single transaction dramatically improves performance (SQLite commits per-statement by default, which is slow for bulk inserts).

Parameters

gpkg	GeoPackage handle.

Returns

SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

swmm_gpkg_close()

SWMM_ENGINE_API void swmm_gpkg_close

(

SWMM_Gpkg

gpkg

)

Close the GeoPackage and free all resources.

Rolls back any uncommitted transaction. NULL-safe.

Parameters

gpkg	GeoPackage handle.

swmm_gpkg_commit()

SWMM_ENGINE_API int swmm_gpkg_commit

(

SWMM_Gpkg

gpkg

)

Commit the current transaction.

Parameters

gpkg	GeoPackage handle.

Returns

SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

swmm_gpkg_create_observed_series()

SWMM_ENGINE_API int swmm_gpkg_create_observed_series	(	SWMM_Gpkg	gpkg,
		const char *	name,
		const char *	variable_name,
		const char *	object_type,
		const char *	object_id,
		const char *	source,
		const char *	units
	)

Create an observed data series.

Associates the series with a model object for sim-vs-observed comparison. Pass NULL for object_type/object_id to create an unlinked series.

Parameters

gpkg	GeoPackage handle.
name	Unique series name (e.g., "USGS_01585200_flow").
variable_name	Variable being measured (e.g., "flow", "depth").
object_type	Model object type ("NODE", "LINK", "SUBCATCH"), or NULL.
object_id	Model object ID, or NULL.
source	Data source description (e.g., "USGS NWIS"), or NULL.
units	Measurement units (e.g., "CMS"), or NULL.

Returns

Series ID (>= 0) on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

swmm_gpkg_gage_count()

SWMM_ENGINE_API int swmm_gpkg_gage_count	(	SWMM_Gpkg	gpkg,
		const char *	simulation_id
	)

swmm_gpkg_is_registered()

SWMM_ENGINE_API int swmm_gpkg_is_registered

(

void

)

Check whether the GeoPackage plugin is registered.

Returns

1 if registered, 0 otherwise.

Here is the call graph for this function:

swmm_gpkg_last_error()

SWMM_ENGINE_API const char * swmm_gpkg_last_error

(

SWMM_Gpkg

gpkg

)

Get the last error message.

Parameters

gpkg	GeoPackage handle.

Returns

Null-terminated error message, or empty string if no error.

swmm_gpkg_link_count()

SWMM_ENGINE_API int swmm_gpkg_link_count	(	SWMM_Gpkg	gpkg,
		const char *	simulation_id
	)

swmm_gpkg_node_count()

SWMM_ENGINE_API int swmm_gpkg_node_count	(	SWMM_Gpkg	gpkg,
		const char *	simulation_id
	)

swmm_gpkg_observed_series_count()

SWMM_ENGINE_API int swmm_gpkg_observed_series_count

(

SWMM_Gpkg

gpkg

)

Get the number of observed series in the GeoPackage.

Parameters

gpkg	GeoPackage handle.

Returns

Series count (>= 0), or SWMM_GPKG_ERR on error.

swmm_gpkg_observed_value_count()

SWMM_ENGINE_API int swmm_gpkg_observed_value_count	(	SWMM_Gpkg	gpkg,
		int	series_id
	)

Get the number of values in an observed series.

Parameters

gpkg	GeoPackage handle.
series_id	Series ID.

Returns

Value count (>= 0), or SWMM_GPKG_ERR on error.

Here is the call graph for this function:

swmm_gpkg_open()

SWMM_ENGINE_API SWMM_Gpkg swmm_gpkg_open

(

const char *

path

)

Open an existing GeoPackage file.

Opens the database in read-write mode. Model definitions and simulation results are read-only by convention — only the observed data tables are writable through this API.

Parameters

path	Path to the .gpkg file (must exist).

Returns

Opaque handle, or NULL on failure.

Here is the call graph for this function:

swmm_gpkg_query_double()

SWMM_ENGINE_API int swmm_gpkg_query_double	(	SWMM_Gpkg	gpkg,
		const char *	sql,
		double *	result
	)

Execute a read-only SQL query and get the first double result.

Parameters

	gpkg	GeoPackage handle.
	sql	SELECT query string.
[out]	result	Pointer to receive the double result.

Returns

SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

swmm_gpkg_query_int()

SWMM_ENGINE_API int swmm_gpkg_query_int	(	SWMM_Gpkg	gpkg,
		const char *	sql
	)

Execute a read-only SQL query and get the first integer result.

Parameters

gpkg	GeoPackage handle.
sql	SELECT query string.

Returns

Integer result, or SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

swmm_gpkg_read_observed_values()

SWMM_ENGINE_API int swmm_gpkg_read_observed_values	(	SWMM_Gpkg	gpkg,
		int	series_id,
		char *	timestamps,
		int	ts_buf_len,
		double *	values,
		int	max_count
	)

Read observed timeseries values into caller-supplied arrays.

Parameters

	gpkg	GeoPackage handle.
	series_id	Series ID.
[out]	timestamps	Array to receive timestamp strings (each must be at least 32 chars). Pass NULL to skip timestamps.
	ts_buf_len	Length of each timestamp buffer (e.g., 32).
[out]	values	Array to receive values. Must hold max_count doubles.
	max_count	Maximum number of values to read.

Returns

Number of values read (>= 0), or SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

swmm_gpkg_read_result_ts()

SWMM_ENGINE_API int swmm_gpkg_read_result_ts	(	SWMM_Gpkg	gpkg,
		const char *	simulation_id,
		const char *	object_type,
		const char *	object_id,
		const char *	variable_name,
		double *	times,
		double *	values,
		int	max_count
	)

Read a result timeseries for one object and variable.

Fills the caller-supplied arrays with elapsed_time and value pairs, ordered by time. Returns the number of values actually read (may be less than max_count if fewer results exist).

Parameters

	gpkg	GeoPackage handle.
	simulation_id	Simulation run identifier.
	object_type	"NODE", "LINK", "SUBCATCH", or "SYSTEM".
	object_id	Object identifier (e.g., "J1").
	variable_name	Variable name (e.g., "depth", "flow").
[out]	times	Array to receive elapsed times (seconds). Must hold max_count doubles.
[out]	values	Array to receive result values. Must hold max_count doubles.
	max_count	Maximum number of values to read.

Returns

Number of values read (>= 0), or SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

swmm_gpkg_read_summary()

SWMM_ENGINE_API int swmm_gpkg_read_summary	(	SWMM_Gpkg	gpkg,
		const char *	simulation_id,
		const char *	object_type,
		const char *	object_id,
		const char *	variable_name,
		double *	value
	)

Read a single summary statistic value.

Parameters

	gpkg	GeoPackage handle.
	simulation_id	Simulation run identifier.
	object_type	"NODE", "LINK", or "SUBCATCH".
	object_id	Object identifier.
	variable_name	Variable name (e.g., "max_depth", "max_flow").
[out]	value	Pointer to receive the statistic value.

Returns

SWMM_GPKG_OK on success, SWMM_GPKG_ERR if not found.

Here is the call graph for this function:

swmm_gpkg_register()

SWMM_ENGINE_API int swmm_gpkg_register	(	const char *	license_key,
		const char *	organization,
		const char *	contact_email,
		const char *	deployment_id
	)

Register the GeoPackage plugin.

Parameters

license_key	License key or activation token (may be NULL).
organization	Registering organization name (may be NULL).
contact_email	Contact email (may be NULL).
deployment_id	Deployment identifier (may be NULL).

Returns

1 if registration succeeded, 0 otherwise.

Here is the call graph for this function:

swmm_gpkg_result_ts_count()

SWMM_ENGINE_API int swmm_gpkg_result_ts_count	(	SWMM_Gpkg	gpkg,
		const char *	simulation_id,
		const char *	object_type,
		const char *	object_id,
		const char *	variable_name
	)

Get the number of result timeseries records for a query.

Use this to pre-allocate arrays before calling swmm_gpkg_read_result_ts().

Parameters

gpkg	GeoPackage handle.
simulation_id	Simulation run identifier.
object_type	"NODE", "LINK", "SUBCATCH", or "SYSTEM".
object_id	Object identifier.
variable_name	Variable name.

Returns

Record count (>= 0), or SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

swmm_gpkg_rollback()

SWMM_ENGINE_API int swmm_gpkg_rollback

(

SWMM_Gpkg

gpkg

)

Roll back the current transaction.

Parameters

gpkg	GeoPackage handle.

Returns

SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

swmm_gpkg_simulation_count()

SWMM_ENGINE_API int swmm_gpkg_simulation_count

(

SWMM_Gpkg

gpkg

)

Get the number of simulation runs in the GeoPackage.

Parameters

gpkg	GeoPackage handle.

Returns

Simulation count, or -1 on error.

swmm_gpkg_simulation_id()

SWMM_ENGINE_API int swmm_gpkg_simulation_id	(	SWMM_Gpkg	gpkg,
		int	index,
		char *	buf,
		int	bufsz
	)

Get the simulation_id at the given index.

Parameters

gpkg	GeoPackage handle.
index	Zero-based index (ordered by creation time).
buf	Buffer to receive the null-terminated simulation_id.
bufsz	Size of the buffer.

Returns

SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

swmm_gpkg_subcatch_count()

SWMM_ENGINE_API int swmm_gpkg_subcatch_count	(	SWMM_Gpkg	gpkg,
		const char *	simulation_id
	)

swmm_gpkg_topology_edge_count()

SWMM_ENGINE_API int swmm_gpkg_topology_edge_count	(	SWMM_Gpkg	gpkg,
		const char *	simulation_id
	)

swmm_gpkg_variable_count()

SWMM_ENGINE_API int swmm_gpkg_variable_count

(

SWMM_Gpkg

gpkg

)

swmm_gpkg_write_observed_value()

SWMM_ENGINE_API int swmm_gpkg_write_observed_value	(	SWMM_Gpkg	gpkg,
		int	series_id,
		const char *	timestamp,
		double	value,
		const char *	quality_flag
	)

Write a single observed data point.

Parameters

gpkg	GeoPackage handle.
series_id	Series ID from swmm_gpkg_create_observed_series().
timestamp	ISO 8601 timestamp (e.g., "2026-01-15T08:30:00Z").
value	Measured value.
quality_flag	Quality flag ("A", "P", "E"), or NULL.

Returns

SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

swmm_gpkg_write_observed_values()

SWMM_ENGINE_API int swmm_gpkg_write_observed_values	(	SWMM_Gpkg	gpkg,
		int	series_id,
		const char **	timestamps,
		const double *	values,
		const char **	quality_flags,
		int	count
	)

Bulk-write a vector of observed data points to a series.

Inserts count timestamp/value pairs in a single prepared-statement loop. For best performance, wrap in a transaction:

swmm_gpkg_begin(gpkg);
swmm_gpkg_write_observed_values(gpkg, sid, times, vals, flags, 10000);
swmm_gpkg_commit(gpkg);

Parameters

gpkg	GeoPackage handle.
series_id	Series ID from swmm_gpkg_create_observed_series().
timestamps	Array of ISO 8601 timestamp strings (count elements).
values	Array of measured values (count elements).
quality_flags	Array of quality flag strings (count elements), or NULL to omit quality flags for all values.
count	Number of data points to write.

Returns

SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function: