---

name: api-variants description: "Select and interoperate among h3-py's string, integer, memoryview, and optional NumPy APIs while preserving H3 index meaning and collection contracts." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

API variants

Use this route when a task mentions H3 string or integer indices, NumPy arrays, memoryview, API parity, int_to_str, str_to_int, conversion, memory, performance, or optional NumPy installation. The four public variants expose the same public function names and signatures, but change scalar and collection representations:

• import h3 is the default h3.api.basic_str interface.
• h3.api.basic_int uses Python integers and ordinary Python collections.
• h3.api.memview_int uses Python integers and typed uint64 buffer outputs; it has no NumPy dependency.
• h3.api.numpy_int uses Python integers for scalar results and NumPy ndarray collections with uint64 dtype; NumPy is optional.

Route the task

1. Keep strings at the application boundary when logs, JSON, config files, or human review are primary: use h3/h3.api.basic_str.
2. Keep integer scalars and ordinary Python iteration when the consumer already uses integer H3 values but does not need a buffer: use basic_int.
3. Use memview_int for dependency-free typed-buffer exchange. Supply a uint64 buffer, not a list or set, and preserve the returned view's lifetime.
4. Use numpy_int when downstream code already consumes NumPy arrays or needs vectorized array handling. Install the optional NumPy extra first.
5. For a mixed pipeline, compute in an integer/buffer variant and normalize once at the boundary. Measure the actual workload before making performance claims; documentation timing examples are illustrative, not universal.

Read the root router for overall H3 routing. For geographic indexing algorithms, use core-indexing; for polygon and shape workflows, use polygon-geospatial.

Operating rules

• Treat an H3 string as a hexadecimal representation without assuming a 0x prefix. str_to_int and int_to_str are the explicit conversion boundary.
• Do not mix a string scalar into an integer API or an integer scalar into the string API without converting it first.
• Normalize collections element by element when crossing APIs. Do not compare a string collection directly with an integer or NumPy collection.
• Preserve collection semantics separately from representation: choose whether order and duplicates matter, then use a list, set, or sorted canonical list deliberately. API output types are not a substitute for domain semantics.
• Treat NumPy and memoryview outputs as unsigned 64-bit H3 values. Validate ranges before constructing buffers; do not use signed buffers for memview_int.
• np.asarray(view) can share the memoryview's storage, whereas np.array(view) makes an independent copy. Choose deliberately before mutating or retaining a result.
• The public API surface is shared across variants, with representation-specific exceptions documented in the reference.

Common actions

• Compare or serialize outputs: normalize to strings with int_to_str/str_to_int as described in workflows.
• Accept user-facing indices: validate the scalar type and convert at the boundary; see troubleshooting for invalid hex, overflow, and collection errors.
• Diagnose an installation or representation issue: run python scripts/check_api_variants.py. It reports available variants, scalar/collection types, NumPy dtype, and a tiny parity check without running a geospatial benchmark.

Handoff checklist

Before handing a result to another component, record:

1. Which API module owns each scalar and collection value.
2. Whether collection order, duplicates, or set semantics are significant.
3. Whether the consumer requires a copied snapshot or may share a buffer.
4. Whether NumPy is a required dependency or only an optional fast path.
5. Which conversion boundary turns values back into the consumer's contract.

When an API boundary is part of a public function, document the accepted scalar and collection representation rather than relying on a module import name. For reproducibility, include the package version and the diagnostic output, but keep those task artifacts outside this runtime skill tree.

If a caller can select more than one variant, expose the choice as an explicit configuration value and test both the selected representation and the normalized semantic result. Do not switch variants implicitly because an optional import happens to be present. A missing optional dependency should produce a clear fallback or a clear installation error, depending on the caller's contract.

Deliberate non-coverage

This route does not teach cell geometry, hierarchy, grid algorithms, edge/vertex algorithms, or polygon construction. Follow the sibling routes above for those operations, then return here only for representation conversion or interop.

Keep this route focused on public Python behavior and observable contracts.