🗺️ 静态地图API文档

高质量静态地图服务

🚀 在线测试

📍 标记样式设置

注:推荐使用Awesome或Material类型获得更丰富的图标选择
输入坐标后点击生成地图按钮

📖 API文档

静态地图服务

GET
/map

描述:获取指定位置的静态地图图片

支持参数:center, zoom, width, height, format, style, marker, scaleFactor等

请求参数

参数名 类型 必填 说明 示例
center string 地图中心点坐标,格式:lonlat:经度,纬度 lonlat:116.4074,39.9042
zoom number 缩放级别 (1-20),默认15 15
width number 图片宽度 (最大2048px),默认600 600
height number 图片高度 (最大2048px),默认400 400
style string 地图样式,默认osm-carto osm-carto, dark-matter, positron
format string 图片格式,必须指定 png, jpg
marker string 标记点,格式:lonlat:经度,纬度;type:类型;color:颜色;size:大小;icon:图标;icontype:图标库
支持多个标记,用|分隔
lonlat:116.4074,39.9042;type:awesome;color:%23ff0000;size:64;icon:marker;icontype:awesome
scaleFactor number 缩放因子 (1-2),用于高分辨率显示 2

地图样式说明

样式名称 描述 适用场景
osm-carto 标准OpenStreetMap样式 通用地图显示
osm-bright 明亮的OSM样式 清晰的街道显示
dark-matter 深色主题地图 夜间模式、数据可视化
positron 浅色简洁样式 数据叠加、简洁显示
klokantech-basic 基础样式 简单地图需求

标记样式参数说明

参数 可选值 说明 示例
type material, awesome, circle, plain 标记形状类型,plain为无背景形状 type:awesome
color 十六进制颜色值(URL编码) 标记颜色,需要URL编码(#号编码为%23) color:%23ff0000(红色)
size 16-128 标记大小(像素) size:64
icon marker, home, star, heart, flag, circle, square, h-square, plus, minus, times, check等Font Awesome图标 图标类型,支持Font Awesome v6图标库 icon:marker
icontype material, awesome 图标库类型,material使用Material Design图标 icontype:awesome
text 任意文本 显示文本而不是图标,会覆盖icon参数 text:1
contentsize 数字(像素) 内部内容(图标或文本)的高度,可选参数 contentsize:40
contentcolor 颜色名或十六进制 内部图标或文本的颜色 contentcolor:%230099ff
whitecircle yes, no 是否在内容后面显示白色圆圈,plain类型忽略 whitecircle:no
shadow auto, no 是否在标记下方显示阴影 shadow:no
shadowcolor RGBA颜色值 标记阴影的颜色 shadowcolor:rgba(0,0,0,0.3)
strokecolor 颜色名或十六进制 标记背景形状的轮廓颜色,plain类型忽略 strokecolor:%230077ff

💡 标记使用技巧

  • 多个标记:使用 | 分隔多个标记,如:marker1|marker2
  • 颜色编码:颜色值中的 # 需要编码为 %23
  • 常用颜色:红色(%23ff0000)、绿色(%2300ff00)、蓝色(%230000ff)
  • 大小建议:32px适合密集标记,64px适合重要标记,80px适合突出显示
  • 标记类型:支持material、awesome、circle、plain四种类型
  • 方形标记:使用type:awesome配合icon:square,或type:material配合相应方形图标
  • 文本标记:使用 text 参数可以显示文本而不是图标,如 text:1 显示数字1
  • 颜色自定义:使用 color 设置背景色,contentcolor 设置图标/文本颜色,strokecolor 设置边框颜色
  • 尺寸调整:使用 size 调整标记整体大小,contentsize 调整内部图标/文本大小
  • 阴影效果:使用 shadow:auto 启用阴影,shadowcolor 自定义阴影颜色
  • 白色圆圈:使用 whitecircle:yes 在图标后面添加白色圆圈背景(plain类型除外)

请求示例

🗺️ 基础地图
GET /map?style=osm-carto&width=600&height=400&center=lonlat:116.4074,39.9042&zoom=15&format=png
获取北京天安门的标准地图
📍 带标记的地图
GET /map?style=osm-carto&width=600&height=400&center=lonlat:116.4074,39.9042&zoom=15&marker=lonlat:116.4074,39.9042;type:awesome;color:%23ff0000;size:64;icon:marker;icontype:awesome&format=png
在地图上添加标记点
🎨 自定义样式
GET /map?style=dark-matter&width=800&height=600&center=lonlat:116.4074,39.9042&zoom=15&scaleFactor=2&format=png
使用暗色主题,高分辨率地图
🌍 多个标记点
GET /map?style=positron&width=800&height=600&center=lonlat:116.4074,39.9042&zoom=12&marker=lonlat:116.4074,39.9042;type:awesome;color:%23ff0000;size:64;icon:marker;icontype:awesome|lonlat:116.3974,39.9142;type:circle;color:%2300ff00;size:48;icon:circle;icontype:awesome&format=png
在地图上添加多个不同样式的标记点
📝 文本标记
GET /map?style=osm-carto&width=600&height=400&center=lonlat:116.4074,39.9042&zoom=15&marker=lonlat:116.4074,39.9042;type:awesome;text:1;color:%23ff6600;contentcolor:%23ffffff;size:64&format=png
使用文本标记显示数字或字母
🎨 自定义颜色标记
GET /map?style=osm-bright&width=600&height=400&center=lonlat:116.4074,39.9042&zoom=15&marker=lonlat:116.4074,39.9042;type:awesome;icon:star;color:%23ffeb3b;contentcolor:%23e65100;strokecolor:%23ff5722;whitecircle:yes;size:64&format=png
自定义背景色、图标色和边框色的标记
🌟 带阴影的Material标记
GET /map?style=positron&width=600&height=400&center=lonlat:116.4074,39.9042&zoom=15&marker=lonlat:116.4074,39.9042;type:material;icon:place;color:%234285f4;shadow:auto;shadowcolor:rgba(0,0,0,0.4);size:64&format=png
使用Material Design图标并添加阴影效果
🏠 无背景标记
GET /map?style=osm-carto&width=600&height=400&center=lonlat:116.4074,39.9042&zoom=15&marker=lonlat:116.4074,39.9042;type:plain;icon:home;contentcolor:%232196f3;contentsize:50;size:64&format=png
使用plain类型创建无背景的纯图标标记

响应格式

# 成功响应 Content-Type: image/png [PNG图片二进制数据] # 错误响应 HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "Invalid center parameter", "message": "Center parameter must be in format: lonlat:longitude,latitude" }

⚠️ 使用说明

  1. 图片尺寸限制:最大2048x2048像素
  2. 缩放级别范围:1-20,数值越大显示越详细
  3. 坐标格式必须为:lonlat:经度,纬度(注意经纬度顺序)
  4. 标记点支持多种类型和样式,用|分隔多个标记
注意:请合理使用API,避免频繁请求。服务可能会根据使用情况进行限流。