NewLife.Map 2.8.2026.1024

NewLife.Map - Unified Map Component Library

🌐 简体中文 | 繁體中文 | Español | Deutsch | 日本語 | Français | Português | Русский | 한국어 | العربية

A map component library that unifies Baidu, AMap, Tencent, Tianditu and the enterprise map API platform behind a single interface. It hides vendor differences and provides geocoding, reverse geocoding, distance calculation, coordinate conversion and multi-key circuit breaking.

Source: https://github.com/NewLifeX/NewLife.Map
NuGet: NewLife.Map

Repository layout

Documentation

• Requirements — vision, core goals, functional requirements, deferred list
• Feature list — module/feature codes with three-dimensional status tracking (implementation/test/comments)
• Architecture — layering, components, key flows and design decisions
• Competitive analysis — comparison matrix and gap analysis versus Geocoding.net / ProjNET / domestic single-vendor wrappers

Features

• Unified IMap interface that hides the differences between Baidu / AMap / Tencent / Tianditu / enterprise self-hosted (NewLifeMap); switching vendors requires zero code changes
• Geocoding (address → coordinates) / reverse geocoding (coordinates → address), automatically merging POI semantic information to complete address components
• Route distance / driving time, with vendor-specific strategy parameters abstracted away
• Administrative division queries (AMap / Tencent), POI / region search (Baidu / Tianditu), IP location (Baidu / Tencent / platform online resolution)
• Coordinate system conversion: built-in offline formulas for WGS84 / GCJ02 / BD09 + vendor online batch conversion (Baidu's special from/to mapping is encapsulated)
• Multi-key rotation with automatic circuit breaking + scheduled recovery; a single key being rate-limited or banned does not affect overall availability
• Token-bucket rate limiting via MaxQps and request statistics (total / success rate / average latency), preventing a single key from being banned by high-frequency requests
• Optional exception throwing via ThrowException, making unified handling easier for upper layers
• Multiple target frameworks: net45 / net461 / netstandard2.0 / netstandard2.1 (compatible with legacy projects and modern .NET)
• Strong-name signed, suitable for reflection and plugin systems
• Built-in runtime localization: 11 languages with English as the source and fallback; exception messages, logs and assembly metadata are translated through compile-time locale tables
• Stardust registry integration: the NewLifeMap provider discovers server addresses automatically, enabling seamless switching across multiple instances / blue-green deployments

Installation

# Stable
dotnet add package NewLife.Map
# Preview (date-based)
dotnet add package NewLife.Map --prerelease

Quick start

using NewLife.Map;
using NewLife.Data;

// Choose a concrete map provider (BaiduMap / AMap / WeMap / TianDiTu / NewLifeMap)
var map = new BaiduMap { AppKey = "<BAIDU_AK>" }; // Separate multiple keys with commas

// 1. Forward geocoding: address -> coordinates
var geo = await map.GetGeoAsync("北京市海淀区上地十街10号", city: "北京", coordtype: "bd09ll", formatAddress: true);
Console.WriteLine($"Point: {geo?.Location}  Semantic: {geo?.Title}");

// 2. Reverse geocoding: coordinates -> address
var addr = await map.GetReverseGeoAsync(new GeoPoint(116.30815, 40.056885), "bd09ll");
Console.WriteLine(addr?.Address);

// 3. Distance (driving)
var d = await map.GetDistanceAsync(new GeoPoint(116.30815, 40.056885), new GeoPoint(116.39745, 39.909187), "bd09ll");
Console.WriteLine($"Distance={d?.Distance}m Duration={d?.Duration}s");

// 4. Coordinate conversion (offline formulas)
var list = await map.ConvertAsync(new List<GeoPoint> { new(116.30815, 40.056885) }, from: "wgs84", to: "bd09");
Console.WriteLine(list[0]);

Coordinates must use spherical coordinates (longitude/latitude); the output is a point in the BD09 coordinate system.

Create dynamically through the factory

var m1 = Map.Create("Baidu");           // Automatically matches the *Map suffix
var m2 = Map.Create("AMap");            // AMap
var m3 = Map.Create("NewLifeMap");

// Or create by enum
var m4 = MapFactory.Create(MapKinds.TianDiTu);

AppKey is set after instantiation; multiple keys are separated by commas and rotated internally.

Map providers

To add a provider, see "Steps to extend a new map provider" below and follow the AMap/BaiduMap pattern.

Coordinate system conversion

// Offline formula conversion, no vendor quota consumed
var p = await map.ConvertAsync(new GeoPoint(lng, lat), from: "wgs84", to: "gcj02");

// Baidu online batch conversion, from/to index values already encapsulated
var list = await map.ConvertAsync(points, from: "wgs84ll", to: "bd09ll");

AppKey multi-key rotation and circuit breaking

• Pass AppKey="k1,k2,k3"; each request increments an index and takes the remainder for rotation
• When a response matches invalid keywords (such as TOO_FREQUENT / LIMIT / INVALID), RemoveKey() is called to take that key offline temporarily
• Offline keys enter _pendingKeys and are scanned by a TimerX timer, then restored automatically when due
• Recovery time policy: currently passed in by the caller (for example, 1 hour)

NewLifeMap aggregation platform

NewLifeMap points to the built-in MapApi enterprise map API platform. The platform aggregates multiple vendors and caches results, so clients do not need to be aware of the underlying differences.

// Option 1: specify the server directly
var map = new NewLifeMap("http://mapapi.company.local") { AppKey = "<KEY>" };

// Option 2: dependency injection + Stardust Registry automatic address resolution
services.AddSingleton<IMap, NewLifeMap>();
// The NewLifeMap(IServiceProvider) constructor tries: IRegistry -> StarFactory

• The bound ApiHttpClient automatically updates the server address list, enabling seamless switching during MapApi multi-replica / blue-green deployments
• The platform exposes unified GET /Map/Geo, /Map/ReverseGeo (reverse geocoding), /Map/GeoAddress (forward geocoding) and /Map/Distance (distance) endpoints; a four-level GeoHash cache (6–9 characters) reduces vendor calls

Error handling

• Default: a non-success response does not throw; the method returns null
• With map.ThrowException = true;, an Exception is thrown for unified capture in the outer layer
• Debug information for the most recent request: LastUrl / LastString / LastResult / LastKey

API overview

Task<GeoAddress?> GetGeoAsync(string address, string? city=null, string? coordtype=null, bool formatAddress=false);
Task<GeoAddress?> GetReverseGeoAsync(GeoPoint point, string? coordtype);
Task<Driving?>    GetDistanceAsync(GeoPoint origin, GeoPoint destination, string? coordtype, int type=0);
Task<IList<GeoPoint>> ConvertAsync(IList<GeoPoint> points, string from, string to);

Extensions (provider-specific):

Task<GeoAddress?> PlaceSearchAsync(...);      // BaiduMap / TianDiTu POI / region search
Task<IList<GeoArea>> GetAreaAsync(...);       // AMap administrative divisions
Task<IDictionary<string, object?>> IpLocationAsync(...); // BaiduMap / WeMap IP location

Extending a new map provider

1. Create a class XXXMap : Map, IMap
2. Set Server / KeyName
3. Override InvokeAsync<T> to parse the vendor's unified response structure & error codes
4. Implement GetGeoAsync / GetReverseGeoAsync / other required capabilities
5. If there are vendor-specific rate-limiting / invalidation signals, override IsValidKey to return true and trigger temporary offline
6. Register in the MapFactory static constructor with Register<XXXMap>(MapKinds.XXX)
7. Submit unit tests covering the main functionality and edge cases

Unit tests

The repository contains the XUnitTest project; the solution is NewLife.Map.slnx (VS 2026 / .NET 10 new XML format):

• By default it runs deterministic tests: 84 cases; a local HTTP stub service covers URL construction and response parsing for each vendor; execution takes about 0.4–1 second and runs reliably on all RIDs (including CI)
• Real vendor / OSM / platform online tests are marked Category=Integration and skipped by default via IntegrationFact; "Run All" in the VS Test Explorer behaves the same as dotnet test
• To enable integration tests: first set the environment variable NEWLIFE_MAP_INTEGRATION=1, then run with --filter "Category=Integration"
• Keep real keys in local user secrets or environment variables; never commit them to the repository

Run (Windows PowerShell):

dotnet test -c Release
$env:NEWLIFE_MAP_INTEGRATION = 1
dotnet test -c Release --filter "Category=Integration"   # Optional: live-environment integration

Build

dotnet build -c Release

The output (multi-framework build) is located in Bin/.

Compatibility testing (CI)

Triggered on push / PR, covering mainstream RIDs:

• Unit test matrix: win-x64 / linux-x64 / linux-arm64 / linux-la64 (LoongArch, QEMU emulation + Loongson .NET SDK, see test.yml)
• NativeAOT smoke matrix: the same four RIDs (AotSmoke project, 18 scenarios), see aot.yml

Roadmap / TODO

All completed on 2026-08-04: concurrent rate limiting (MAP-12), failure metrics (MAP-13), benchmark comparison (MAP-14)

Versioning

Major version = compatibility changes; minor version = new features; revision = fixes / optimizations. VersionSuffix carries a date for easy build identification.

Contributing

Issues / PRs are welcome: bugs, performance optimizations, support for more maps, documentation and tests. Before submitting, please read .github/copilot-instructions.md to keep the code style consistent.

License

MIT; keep the copyright notice and you are free to use it in commercial / open-source projects.

Ecosystem Map

NewLife is a layered ecosystem of independently versioned open-source projects. The map below is shared verbatim by every NewLife repository; each project links to its repository and its primary NuGet package.

Project	What it does	Downloads
Foundation
NewLife.Core	Logging, configuration, caching, networking, serialization, scheduling and APM tracing.
NewLife.XCode	Data middleware: single tables at the tens-of-billions scale, automatic sharding, read-write splitting, 10+ databases.
NewLife.Net	High-performance network library: 1.77M pps / 14.5 Gbps on a single machine (TCP 1KB, 2026-10), 4M long-lived TCP connections.
NewLife.Remoting	Protocol communication and RPC framework for client/server applications and IoT devices.
NewLife.Agent	Installs .NET applications as OS daemons: Windows services and Linux systemd.
NewLife.Templates	dotnet new project templates for console, web, API, service, data and IoT projects.
Data & Messaging
NewLife.Redis	Redis client with microsecond latency, millions of ops/s and built-in message queues.
NewLife.RocketMQ	Pure managed RocketMQ client for Apache RocketMQ and Alibaba Cloud Message Queue.
NewLife.MQTT	MQTT client and server, including Alibaba Cloud IoT connectivity.
NewLife.NovaDb	Hybrid database in C#: embedded or networked, relational, time-series, message queue and KV in one.
NewLife.MySql	MySql driver and helper layer built on the NewLife data stack.
Web, AI & Distributed
NewLife.Cube	Rapid admin-platform framework: permissions, SSO, OAuth server and CRUD scaffolding.
Stardust	Distributed service platform: node management, APM, configuration center, registry and release center.
AntJob	Distributed task and real-time data scheduling platform with sharding, retries and backfill.
NewLife.AI	Unified client for 46 LLM providers plus ChatAI, a ready-to-run web chat application.
Industrial & IoT
NewLife.IoT	IoT standard library defining protocol contracts and device abstractions.
NewLife.Modbus	Modbus TCP/RTU/ASCII implementation on top of NewLife.IoT.
NewLife.Siemens	Siemens PLC protocol on top of NewLife.IoT.
NewLife.Omron	Omron PLC protocol on top of NewLife.IoT.
NewLife.Melsec	Mitsubishi Melsec PLC protocol on top of NewLife.IoT.
NewLife.OPC	OPC client for industrial data access.	—
NewLife.BACnet	BACnet building-automation protocol stack.
ZeroIoT	Lightweight open-source IoT platform with gateway and device management.	—
Vehicle Telematics
NewLife.JT808	JT/T 808 vehicle positioning protocol: 70+ message bodies, 2011/2013/2019.
NewLife.JT809	JT/T 809 platform-to-platform protocol for transport authorities.
NewLife.JT1078	JT/T 1078 in-vehicle video: RTP parsing, FLV/fMP4 remuxing and live streaming.
Domain Components
NewLife.Office	One package for Excel, Word, PPT, PDF and 15+ document formats.
NewLife.Audio	Cross-platform audio: codecs, device I/O, DSP, containers and streaming.
NewLife.Video	Video codecs, container formats, frame processing and streaming.
NewLife.Map	Unified interface over Baidu, AMap, Tencent and Tianditu with geocoding and coordinate conversion.
NewLife.IP	IPv4 geolocation with an offline memory-mapped database and an online API fallback.
Tools & Products
CrazyCoder	Developer toolbox: network, serial port, crypto, regex, Modbus and MQTT.
GitCandy	Self-hosted Git source code management system.	—
LuckyClover	Installs the matching .NET runtime automatically when launched from an older host.	—

Badges show the primary package of each project; theme, extension and satellite packages are listed on their NuGet pages.The 30+ packages not listed here (FTP, LoRa, Office extensions, protocol drivers and more) are available under the NewLifeX organization and on newlifex.com.

Team

<img src="https://newlifex.com/logo.png" width="48" align="right" alt="NewLife" />

Founded in 2002, the NewLife team has spent more than two decades on the .NET and IoT ecosystem, maintains nearly 100 open-source projects (34 of them core to this map), and delivers integrated software and hardware solutions for power, logistics, healthcare, industrial control and internet industries. We live by the motto "learning has no seniority — mastery earns respect".

Open-source components have been downloaded 6.48M times from NuGet (ecosystem-wide, as of 2026-10).

Website: https://newlifex.com · Open source organization: https://github.com/NewLifeX

<details> <summary>WeChat Official Account: 智能大石头 (scan to follow)</summary>

</details>