uzmaps_api

uzmaps_api is the typed Dart client for the UzMap HTTP API: search, geocoding, places, routing, photos and status. One client, ten endpoints, typed failures, retry with backoff on transient GET failures and a small TTL cache for the calls that repeat inside a session. Models mirror the TypeScript @uzmaps/api field for field, so web and mobile read the same wire with the same names.

bash

flutter pub add uzmaps_api

Current release: v{{PKG_VER:flutter-api}} · pub.dev: uzmaps_api · source: packages/uzmaps_api

Creating a client#

dart

import 'package:uzmaps_api/uzmaps_api.dart';

final api = UzMapClient(ApiConfig(
  serverUrl: 'https://uzmaps.uz',
  apiKey: 'YOUR_KEY',
  languageKey: 'uz',          // request language: uz | uzc | ru | en
  languageServer: 'uz',       // optional; server language code when it differs
));

The key travels in the X-API-Key header rather than the query string, so it stays out of proxy logs and URLs that end up in crash reports. The two exceptions are places a header cannot go — the map style and photos — where styleUrl() and photoUrl() append ?key= for you.

Endpoints#

Every method returns typed models and throws an ApiFailure on anything that is not data.

Method	Returns	Notes
`search(query, {lat, lon, limit})`	`List<SearchResult>`	Full search; pass `lat`/`lon` to bias results.
`autocomplete(query, {lat, lon, limit})`	`List<SearchResult>`	As-you-type; default limit 8.
`reverse(lat, lon)`	`ReverseResponse`	Coordinates to address — what a map tap resolves to.
`nearby(lat, lon, {category, radius, limit})`	`List<SearchResult>`	Category browse around a point; `radius` in metres.
`place(id)`	`PlaceDetails`	Full details: OSM tags, hours, phone, photo hint, nearby POIs.
`categories()`	`List<CategoryInfo>`	The taxonomy; cached for the client's lifetime.
`photo(wikidata)`	`Photo?`	A Commons photo for a Wikidata Q-id; `null` is an answer, not an error.
`route(points, {mode, alternatives})`	`List<MapRoute>`	Directions. Points are `[lon, lat]`, in travel order.
`status()`	`ServerStatus`	Deployment health; served without a key, never cached hard.
`styleUrl({required dark})`	`String`	MapLibre style URL with the key attached, per theme and language.
`photoUrl(photo)`	`String`	`Image.network`-ready photo URL, key resolved.

matrix and isochrone are on the HTTP API and in the npm client but not yet on the Dart client — file an issue if you need them sooner.

Typed failures#

dart

try {
  final results = await api.search('Chorsu');
} on ApiFailure catch (e) {
  switch (e) {
    case NetworkFailure():      showOffline();
    case TimeoutFailure():      showSlow();
    case HttpFailure(:final status, :final message): showError(status, message);
    case ParseFailure():        showError(0, 'bad response');
  }
}

Every failure carries a human-readable message; HttpFailure adds the HTTP status. Transient failures of idempotent GETs are retried with backoff before they ever surface, so a flaky mobile connection rarely reaches your error UI at all.

Models#

SearchResult, PlaceDetails, ReverseResponse, MapRoute, RouteStep, CategoryInfo, Photo, Address, OpenStatus and ServerStatus — all fromJson-constructible, all documented on the HTTP API reference. The conventions are the API's own: coordinates in method arguments are (lat, lon) while request bodies and geometry use GeoJSON [lon, lat], distances are metres, durations are seconds, and languages are uz, uzc (Cyrillic), ru, en.

ServerMonitor#

A ChangeNotifier that polls status() — every 3 minutes while healthy, every 12 seconds while not — and notifies listeners of transitions. The status dashboard and the offline banner both ride it.

dart

final monitor = ServerMonitor(client: api)..start();
monitor.addListener(() {
  if (monitor.degraded) showBanner();
});

What you get for free#

Retry with backoff on transient GET failures, before your code sees anything.
TTL cache for categories, status and config — the calls that repeat every session.
Cancellation via the underlying http.Client; close() tears the client down.

Pair it with uzmaps_core for formatting (formatDistance, formatDuration) and stores, or jump straight to uzmaps_kit for complete screens.