simbad-resolver
A Rust library for resolving astronomical object names, catalog designations, and sky positions to canonical target identities using SIMBAD.
Given an input such as M31, NGC 224, Andromeda Galaxy, C 14, or a sky
position, simbad-resolver queries SIMBAD and returns a single canonical
identity: a stable id, ICRS J2000 coordinates, an object-type classification,
a Johnson V magnitude when SIMBAD has one (v_mag, None otherwise), the
object's alias set, and the provenance of the record.
Resolved identities are stored in a pluggable cache, so repeated lookups are served locally instead of re-querying SIMBAD. An async batch resolver processes many names against a durable queue.
It is a single crate with no required feature flags: the network resolvers and a redb-backed store (durable or in-memory) ship in the default build.
Documentation
Full API documentation is generated from the source and published on docs.rs:
docs.rs/simbad-resolver. For a
task-oriented walkthrough (resolving a name, testing offline, batching,
storage), see the
guide
(also in this repo at docs/guide.md).
Resolving
Two SIMBAD backends are available, both built in:
TapResolverqueries the SIMBAD TAP service with ADQL. It returns SIMBAD object ids, object types, the full alias set, a Johnson V magnitude (via aLEFT OUTER JOINonallfluxes,Nonewhen the object has no V photometry), and supports cone search by position.SesameResolverqueries the CDS Sesame name resolver, which aggregates SIMBAD, NED, and VizieR. It resolves a broader range of names but returns coordinates and a primary designation only; object type and aliases can be filled in by supplying aTapResolveras an enricher.
Both implement the
Resolver
trait, so either can back a
SimbadResolver
facade or a
BatchResolver.
Caldwell designations (C 14) are not SIMBAD identifiers; the facade
translates them to the underlying catalog designation via
caldwell::caldwell_to_designation
before resolving, then binds the original C n as an alias.
Positions
Resolving by sky position (cone search) is the
PositionResolver
capability, implemented by TapResolver. Its
resolve_position
returns the objects within radius_deg of an ICRS position, nearest first, as
PositionMatch
values. This hits the live endpoint, so it needs network access:
use ;
# async
Search
SimbadResolver::search
is a local, network-free typeahead over cached aliases, ranked exact > prefix >
substring. Enabling fuzzy matching with
ResolverConfig::with_fuzzy
fills remaining result slots with token-set similarity hits in the
RANK_FUZZY
tier. This does not change resolve, which stays exact-normalized.
Overrides
SimbadResolver::apply_override
binds a chosen canonical target as authoritative: it adds the supplied alias
and marks the row sticky (source = user-override), so a later re-resolve does
not overwrite it. See the
guide
for an example.
Storage
The facade selects its cache with a
CacheBackend,
chosen at construction — there is no separate "enable caching" step, because
the cache is load-bearing (resolve returns cached rows). The built-in backend
is redb (a pure-Rust embedded ACID store):
CacheBackend::InMemory— ephemeral, nothing written to disk (alsoDefault).CacheBackend::file("targets.redb")— durable, file-backed; survives restarts.CacheBackend::custom(my_cache)— anyCacheimplementation you supply.
For an uncached one-shot lookup, call a bare Resolver (e.g. TapResolver)
directly instead of the facade.
Under the hood the built-in variants open a
Store
(still public:
Store::open
/
Store::in_memory,
each exposing .cache() and .queue() over one database). Open the Store
yourself to share one database between a SimbadResolver and a BatchResolver:
use ;
#
Coordinates
Resolved-object types
(ResolvedIdentity,
CachedTarget,
and the cone-search
PositionMatch)
keep their canonical ra_deg/dec_deg (f64, ICRS J2000 degrees) and also
expose a typed accessor:
# use ResolvedIdentity;
#
position() returns a skymath::Equatorial
— this crate depends on skymath for that
shared, domain-validated coordinate type, so downstream consumers (ranking,
formatting) share one representation with no conversion. SIMBAD's ICRS output
is treated as J2000 at planning grade (≤ ~1 arcminute); the raw f64 fields
remain the source of truth.
Usage
This calls the live SIMBAD TAP endpoint, so it needs network access to run.
use ;
# async
When a query does not resolve, the
Resolution::Unresolved
reason is a
UnresolvedReason:
Offline (backend unreachable/timed out/disabled — retry later; cached objects
still resolve), Unknown (no such object — give up), or Ambiguous (several
distinct objects — disambiguate the query).
See the guide
for a walkthrough that also covers testing without the network
(OfflineResolver/FakeResolver) and batch resolution.
[]
= "0.2"
Attribution
This library queries SIMBAD, operated at CDS, Strasbourg, France. Applications
that display resolved data should credit CDS and send an identifying
User-Agent header (configurable via SimbadConfig).
License
This project is licensed under the Mozilla Public License 2.0 — see LICENSE for details.
You can use this library in closed-source projects. If you modify any of the source files in this library, the modified files must be made available under the MPL-2.0 when distributed.