Frequently asked questions

Portolan builds directly on STAC, GeoParquet, COG, PMTiles, and related standards. The difference is that those standards intentionally leave many implementation choices open, while Portolan defines and validates a quality floor for publishing geospatial data well.

For example, Portolan requires GeoParquet to be spatially ordered and include spatial statistics that let clients skip irrelevant row groups. It requires COGs to include useful overviews and embedded statistics, and requires hosted assets to support HTTP range requests and browser access through CORS. The goal is not just to use cloud-native formats in name, but to use them in ways that reliably deliver the performance and ergonomics they are supposed to provide.

See the Portolan specification and rashid, the Portolan validator.

For public, read-heavy data, Portolan is based on the idea that a dedicated serving layer is usually unnecessary.

Modern clients can work directly with cloud-optimized files. DuckDB can query remote Parquet and GeoParquet with filtering, joins, and spatial operations. QGIS, BigQuery, Sedona, and other tools can work with the same underlying data. Portolan can also publish PMTiles and styles so interactive web maps do not need an on-demand tile server. You can still put an API, database, or application service on top when a particular use case needs one. Portolan removes the requirement that every dataset depend on one just to be accessible.

Quite a lot.

Cloud-optimized formats are designed for efficient partial access over the network. Instead of downloading an entire dataset or sending every request through a server-side subsetting service, clients can fetch only the portions of a file they need and work with them directly.

That means many capabilities traditionally associated with APIs can happen on top of the files themselves. Tools such as DuckDB, BigQuery, and Sedona can filter, join, subset, and analyze Parquet and GeoParquet directly. COG readers can request only the raster tiles and resolutions needed for a particular view, while PMTiles can serve interactive maps without an on-demand tile server.

Portolan is designed around this model: publish data in formats that support efficient direct access, and let users choose the tools that query, analyze, or visualize them. A service can still be added when a workflow genuinely needs server-side behavior, but it no longer has to sit between every user and every dataset.

Access-controlled data is planned for Portolan v1.0. Transactional editing is not yet supported.

A catalog does not conform simply because it declares the Portolan extension. It conforms only if it passes the Portolan validator, which checks the STAC structure, Portolan metadata requirements, and requirements that can only be verified by inspecting the data itself.

That includes things such as GeoParquet spatial ordering, row-group statistics, and embedded COG statistics. Conformance therefore means more than valid metadata: it gives users and software a stronger guarantee that the data are structured, hosted, documented, and optimized in predictable ways.

Avoiding that is a core part of the architecture. Portolan standardizes the published catalog, not the cloud provider, publishing workflow, user interface, analytical engine, or commercial vendor around it.

If a commercial product creates and manages a Portolan catalog and you later stop using that product, the published catalog still works and another tool, provider, or vendor can take over. The goal is an ecosystem of competing, interoperable implementations rather than a vertically integrated Portolan platform.

No. Portolan standardizes how data are packaged, documented, hosted, and accessed. It does not prescribe one universal schema for roads, buildings, parcels, administrative boundaries, or other domain data.

Semantic standards and shared schemas can sit on top of Portolan where they are useful. Portolan addresses a different layer of interoperability: making differently produced datasets consistently discoverable, queryable, documented, and usable with common tools.

Agents are becoming another major class of data user, and that changes some of the assumptions behind public data infrastructure.

Agents can inspect and query many datasets quickly, so Portolan assumes catalogs will be consumed programmatically at scale. Every catalog and collection therefore includes an AGENTS.md file that can document access patterns, useful queries, data-quality notes, schema conventions, and other guidance that helps software use the data correctly.

Agents are not required to publish or consume Portolan data. The CLI provides a deterministic publishing workflow, and standard tools can use the resulting catalogs directly. Agent-readiness is a design requirement, not a dependency on any particular AI system.

Portolan is still early-stage, and the specification and tooling are evolving as we test them against more publishers, datasets, and use cases. Current gaps include access-controlled data, transactional editing workflows, and normative support for formats such as Zarr and COPC.

Our near-term focus is to expand the set of reference catalogs, stabilize the core specification, and reach a stable v1.0 CLI. Breaking changes remain possible until then, so Portolan is currently best suited to early adopters. See the project roadmap for current work and linked issues.

Portolan charts were among the earliest practical navigational maps. Chartmakers built these working tools from sailors' observations and corrected them as new voyages added evidence.

No single authority made them. Workshops in different ports refined them as sailors brought new observations. Their shared visual language let sailors use each chart across ports and nations.

The project takes its name from that tradition. A Portolan catalog is a practical tool, not an academic exercise. It holds open-format files in the publisher's storage for people and agents across organizations, clouds, and borders.