Skip to Content
teigeodata
Reference

Types, constants and errors

The options records, their enums, the limits and every error code, as each language names them.

Options records

Every field's zero value is its default, so a record made with no fields set asks for the defaults (in C, a null pointer does too). Each language spells a field its own way: focus_lat is focusLat in JavaScript, Swift, Java, Kotlin and Dart, and FocusLat in Go and C#.

SearchOptions

How Engine::search_with ranks. Every field's zero value is its default.

FieldTypeDefaultWhat
focus_latOption<f64>nonePrefer places near this latitude (with focus_lon): the user's location, or a point in their home country with a wide scale.
focus_lonOption<f64>noneThe focus longitude; set with focus_lat or not at all.
focus_scale_mOption<f64>noneThe distance in metres at which the focus gain halves (a place at the focus gains 30, one scale away 15); None is 50 km.
strictboolfalseRank by match tier first (exact, loose, prefix, one edit, substring, two edits, phonetic), then importance and focus, instead of one additive score.

OpenOptions

How Engine::open_file_with and Engine::open_bytes_with open a pack. Every field's zero value is its default.

FieldTypeDefaultWhat
priorityi320Precedence over the other packs: a higher one wins where packs disagree (default 0).
verifyVerifyLazyWhen sections are verified.
loadLoadMapHow a file is loaded; ignored for bytes.
outline_levelOption<u32>noneThe deepest admin level whose outlines are read, in a pack that splits its outlines by level: admin units below it are not found at a point, and their outlines are not loaded. None reads every level.
outline_tolerance_mu320The largest simplification of the outlines read, in metres, when the pack has coarser outlines; 0 is full resolution. Admin units at a point may then differ within that distance of a border.
componentsStringemptyThe components the pack holds, by name and comma-separated (point,names,search), for a pack installed in part; what they need is added. Empty for a whole pack. A query that needs a component left out answers nothing, or MissingComponent where it cannot.
languagesStringemptyThe languages whose names and search sections are read, as comma-separated BCP 47 tags (en,ne), at most 8; a language without a part of its own reads the pack's shared part. Empty reads every language.

InstallOptions

What Store::install takes of each pack. Every field's zero value is its default: the whole pack.

FieldTypeDefaultWhat
componentsStringemptyThe components, by name and comma-separated (point,names,search); what they need is added. Empty for every component.
languagesStringemptyThe languages besides the base names, as comma-separated BCP 47 tags (en,ne), at most 8. Empty for every language.
outline_levelOption<u32>noneThe deepest admin level of the one outline part installed; None for every outline.
outline_tolerance_mu320The tolerance in metres of that outline part; 0 is full resolution.
pinboolfalseKeeps the packs when room is made.

Enums

Verify

When a pack's sections are verified against their hashes.

VariantValueWhat
Lazy0On first use: each section, or each 16 KiB block of a large one, is checked the first time a query reads it. Opening costs only the head checks.
Eager1Every section when the pack opens.
Trusted2Never: only for bytes already verified, by the store's installer for instance.

Load

How a pack file is loaded.

VariantValueWhat
Map0Map the file into memory where the platform can, read it otherwise. The file must not be written over while it is open.
Read1Read the whole file into memory: for files the application does not own.

Constants

ConstantValueWhat
SAMPLE_ROWS_MAX1000000Most rows sample_rows builds in one call.
LIMIT_MAX10000Most places one query returns.
COARSEST_LOD6The coarsest level of detail Engine::boundary reads; 0 is full resolution.

Errors

A call that fails gives one of these codes and a message, the same in every language. Each language raises it in its own way:

LanguageA failure is
Rustteigeodata_api::Error, with code (an ErrorCode) and message
PythonTeiGeodataError, or its subclass for the code: InvalidArgumentError, CancelledError, InternalError, IoError, CorruptError, MissingComponentError, NetworkError, RefusedError
JavaScriptan Error whose code is the code's name, such as "InvalidArgument"
Swifta thrown TeiGeodataError, with code (TeiGeodataError.Code)
Java and KotlinTeiGeodataException (unchecked), or its subclass for the code, such as TeiGeodataException.Cancelled; code() gives the value
Dartthe sealed TeiGeodataException: InvalidArgumentException, CancelledException, InternalException, IoException, CorruptException, MissingComponentException, NetworkException, RefusedException
Goan error holding a *teigeodata.Error; test it with errors.Is(err, teigeodata.CodeInvalidArgument)
Cthe code as the return value (0 is success); tg_last_error gives the message on the same thread
C++teigeodata::Error (a std::runtime_error), with code()
.NETTeiGeodataException, with Code (an ErrorCode)
CodeValueMeaning
InvalidArgument1An argument is outside its documented range.
Cancelled2A callback asked to stop.
Internal3A bug inside teigeodata (a panic caught at the boundary, or a broken invariant).
Io4A file could not be read.
Corrupt5The bytes are not a valid pack, or a section does not match its hash.
MissingComponent6The query needs a component of a pack that is not installed: install it, or ask a pack that has it.
Network7The network failed: no mirror answered, or the connection broke. Try again later.
Refused8The store refused: the catalog did not verify, a pack is not in it or not installed, a pack another needs, or the store's files cannot be written.

On this page