目录

Maps Static API

功能介绍

静态图服务通过发送Http请求返回一张地图图片,您可以指定请求的地图位置、图片大小、以及在地图上添加覆盖物,如标签、折线、多边形。

图1 标签
图2 多边形
图3 折线

场景描述

通过HTTP请求发送的URL参数创建地图图片并直接嵌入到网页中,而无需通过JavaScript或动态页面加载。

使用约束

服务调用量的限制请查看服务定价。

接口原型

承载协议

HTTPS GET

接口方向

开发者服务器 -> 华为地图服务器

接口URL

https://mapapi.cloud.huawei.com/mapApi/v1/mapService/getStaticMap

数据格式

响应消息:Content-Type: image/png

请求参数

Request Header中的Authorization和Query String中的key至少需要存在一个。

Request Header

参数

是否必选

参数类型

描述

Content-Type

是

application/json

请求消息的数据格式。

Authorization

否

String

AT或者API Key,推荐用AT。

说明:

AT认证

API KEY认证

  • 获取API KEY的方式请参见获取API密钥。
  • 使用“API密钥”时需要调用URLEncoder.encode("Your apiKey", "UTF-8")方法对API密钥进行encodeURI编码。例如,原始API密钥:ABC/DFG+ ,转换结果:ABC%2FDFG%2B。
  • 建议“API密钥”设置安全保护措施,具体请参见如何保护API密钥。

Query String

参数

是否必选

参数类型

描述

key

否

String

鉴权密钥,申请参见获取API密钥。

说明:
  1. 获取API KEY的方式请参见获取API密钥。
  2. 使用API key时需要调用URLEncoder.encode("Your apiKey", "UTF-8")方法对API key进行encodeURI编码。例如:原始API key:ABC/DFG+ ,转换结果:ABC%2FDFG%2B。

width

是

Integer

图片宽度。

取值范围:(0, 1024]。

height

是

Integer

图片高度。

取值范围:(0, 1024]。

location

否

String

地址信息,支持经纬度、地址。经纬度采用逗号分隔,经纬度格式是:latitude,longitude,例如:41.43206,-81.38992,如无markers/path则是必选。

zoom

否

int

缩放级别,如无markers/path则是必选。取值范围:[1, 18]。

scale

否

Integer

清晰度比较尺。默认值为1,有效值为1和2。

pattern

否

String

图片格式,当前只支持PNG。

mapType

否

String

标准roadmap,当前暂只支持标准roadmap。

language

否

String

图片显示语种,语言编码支持ISO 639-2 Code和BCP47。推荐使用BCP47,取值范围参见支持的语言。

markers

否

String

marker描述信息,支持Marker样式、经纬度或地址,支持输入多组位置信息,通过|分开。

markers=Marker样式|{纬度1,经度1}|{纬度2,经度2}|地址,如果不指定Marker样式,使用markerStyles作为默认样式。

说明:

markers/path和location/zoom至少需要输入一组。如果都存在,以location/zoom为主。

markerStyles

否

String

marker样式描述信息,可指定的属性包括:

  • size
  • label
  • color
  • icon

参考样例: size:mid|color:black|label:C|icon:https%253A%252F%252Fwww-file.huawei.com%252F-%252Fmedia%252Fcorporate%252Fimages%252Fhome%252Flogo%252Fhuawei_logo.png。

说明:
  1. icon属性将自定义marker显示的图标,此时size、color属性将不再生效。
  2. icon对应的URL地址必须为可以从互联网下载到的PNG格式图片,图片可以是长方形,大小不能大于16KB,像素不超过128*128。
  3. 由于该接口为GET类型,发送请求后会被自动进行一次URL解码,因此icon对应的属性值必须进行两次URL编码。

path

否

String

Path描述信息,支持Path样式、经纬度或地址,支持输入多组位置信息,通过|分开。

path=Path样式|{纬度1,经度1}|{纬度2,经度2}|地址,如果不指定Path样式,使用pathStyles作为默认样式。

说明:

markers/path和location/zoom至少需要输入一组。如果都存在,以location/zoom为主。

pathStyles

否

String

path样式描述信息,可指定的属性包括:

  • color
  • weight
  • fillcolor

如果有fillcolor,表示path是多边形,否则是折线。

参考样例:color:0x0000ff80|weight:1|fillcolor:0x0000ff80。

logo

否

String

logo样式描述信息,可指定属性包括logoAnchor、visible。

  • logoAnchor取值包括:
    • bottomleft:左下(默认)
    • bottomright:右下
    • topleft:左上
    • topright:右上
  • visible取值包括:
    • true:logo可见(默认)
    • false:logo不可见

    静态图logo默认显示在左下角。

参考样例:logoAnchor:bottomleft|visible:true。

signature

否

String

签名,通过签名密钥加密生成的消息签名。推荐使用该签名功能,与API密钥联合控制保证接口安全性。

说明:

获取签名密钥的方式请参见获取签名密钥。

presetStyleId

否

String

支持设置地图预置样式,可指定的属性包括:

  • standard:标准样式(默认)
  • night:深色样式
  • simple:简单样式

请求示例

GET
https://mapapi.cloud.huawei.com/mapApi/v1/mapService/getStaticMap?
width=1024&
height=512&
location=41.43206,-81.38992&
scale=1&
zoom=5&
language=en&
logo=logoAnchor:bottomleft&
markers={41.43206,-81.38992}&
markers={43.43206,-85.38992}&
markerStyles=size:tiny|color:blue|label:p&
path={41.43206,-81.38992}|{43.43206,-85.38992}&
path=fillcolor:red|{41.43206,-81.38992}|{43.43206,-85.38992}|{39.43206,-83.38992}&
pathStyles=weight:1|color:0x0000ff80|fillcolor:0x0000ff80&
key=xxx&
signature=xxx

转义后:

GET
https://mapapi.cloud.huawei.com/mapApi/v1/mapService/getStaticMap?
width=1024&
height=512&
location=41.43206,-81.38992&
scale=1&
zoom=5&
language=en&
logo=logoAnchor:bottomleft&
markers=%7B41.43206,-81.38992%7D&
markers=%7B43.43206,-85.38992%7D&
markerStyles=size:tiny%7Ccolor:blue%7Clabel:p&
path=%7B41.43206,-81.38992%7D%7C%7B43.43206,-85.38992%7D&
path=fillcolor:red%7C%7B41.43206,-81.38992%7D%7C%7B43.43206,-85.38992%7D%7C%7B39.43206,-83.38992%7D&
pathStyles=weight:1%7Ccolor:0x0000ff80%7Cfillcolor:0x0000ff80&
key=xxx&
signature=xxx

请求时需要对符号进行转义,’|‘符号转义为%7C,’{‘ 符号转义为%7B,’}‘ 符号转义为%7D。

响应参数

状态码为200时:

Response Header

参数

是否必选

参数类型

描述

Content-Type

是

image/png

响应消息的数据格式。

Response Body

参数

参数类型

描述

Body

String

静态图。

调用示例

[h2]不使用签名示例代码

“AT认证” 
public class GetStaticMapService {
    OkHttpClient client = new OkHttpClient();

    Request request = new Request.Builder()
            .url("https://mapapi.cloud.huawei.com/mapApi/v1/mapService/getStaticMap?" +
                    // 设置返回图片宽度为1024
                    "width=1024&" +
                    // 设置返回图片高度为512
                    "height=512&" +
                    // 地址信息,纬度:41.43206,经度:-81.38992
                    "location=41.43206%2C-81.38992&" +
                    // 设置清晰度比较尺为1
                    "scale=1&" +
                    // 设置缩放级别为5
                    "zoom=5&" +
                    // 设置图片格式:png
                    "pattern=PNG&" +
                    // 设置图片显示的语言为英语
                    "language=en&" +
                    // logo样式描述
                    "logo=logoAnchor%3Abottomleft&" +
                    // maker描述信息,纬度:41.43206,经度:-81.38992
                    "markers=%7B41.43206%2C-81.38992%7D&" +
                    // maker描述信息,纬度:43.43206,经度:-85.38992
                    "markers=%7B43.43206%2C-85.38992%7D&" +
                    // maker样式描述信息
                    "markerStyles=size%3Atiny%7Ccolor%3Ablue%7Clabel%3Amjy&" +
                    // path描述信息,{纬度,经度}:{41.43206,-81.38992}|{43.43206,-85.38992}
                    "path=%7B41.43206%2C-81.38992%7D%7C%7B43.43206%2C-85.38992%7D&" +
                    // path描述信息,样式为红色,{纬度,经度}:{41.43206,-81.38992}|{43.43206,-85.38992}|{39.43206,-83.38992}
                    "path=fillcolor%3Ared%7C%7B41.43206%2C-81.38992%7D%7C%7B43.43206%2C-85.38992%7D%7C%7B39.43206%2C-83.38992%7D&" +
                    // path样式描述信息
                    "pathStyles=weight%3A1%7Ccolor%3A0x0000ff80%7Cfillcolor%3A0x0000ff80&")
            .addHeader("Authorization", "Bearer " + AT)
            .get()
            .build();

    Response response = client.newCall(request).execute();
}
“API KEY认证”
public class GetStaticMapService {
    OkHttpClient client = new OkHttpClient();

    Request request = new Request.Builder()
            .url("https://mapapi.cloud.huawei.com/mapApi/v1/mapService/getStaticMap?" +
                    // 设置返回图片宽度为1024
                    "width=1024&" +
                    // 设置返回图片高度为512
                    "height=512&" +
                    // 地址信息,纬度:41.43206,经度:-81.38992
                    "location=41.43206%2C-81.38992&" +
                    // 设置清晰度比较尺为1
                    "scale=1&" +
                    // 设置缩放级别为5
                    "zoom=5&" +
                    // 设置图片格式:png
                    "pattern=PNG&" +
                    // 设置图片显示的语言为英语
                    "language=en&" +
                    // logo样式描述
                    "logo=logoAnchor%3Abottomleft&" +
                    // maker描述信息,纬度:41.43206,经度:-81.38992
                    "markers=%7B41.43206%2C-81.38992%7D&" +
                    // maker描述信息,纬度:43.43206,经度:-85.38992
                    "markers=%7B43.43206%2C-85.38992%7D&" +
                    // maker样式描述信息
                    "markerStyles=size%3Atiny%7Ccolor%3Ablue%7Clabel%3Amjy&" +
                    // path描述信息,{纬度,经度}:{41.43206,-81.38992}|{43.43206,-85.38992}
                    "path=%7B41.43206%2C-81.38992%7D%7C%7B43.43206%2C-85.38992%7D&" +
                    // path描述信息,样式为红色,{纬度,经度}:{41.43206,-81.38992}|{43.43206,-85.38992}|{39.43206,-83.38992}
                    "path=fillcolor%3Ared%7C%7B41.43206%2C-81.38992%7D%7C%7B43.43206%2C-85.38992%7D%7C%7B39.43206%2C-83.38992%7D&" +
                    // path样式描述信息
                    "pathStyles=weight%3A1%7Ccolor%3A0x0000ff80%7Cfillcolor%3A0x0000ff80&" +
                    "key=xxxx")
            .get()
            .build();

    Response response = client.newCall(request).execute();
}
图4 获取静态图

[h2]使用签名示例代码

“AT认证” 
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Base64;
import java.util.List;
import java.util.SortedMap;
import java.util.TreeMap;

import javax.crypto.Mac;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;

import okhttp3.HttpUrl;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

public class Demo {
    public static void main(String[] args) throws Exception {
        new Demo().getStaticMapWithUrlSignature();
    }

    private void getStaticMapWithUrlSignature() throws NoSuchAlgorithmException, InvalidKeyException, IOException {
        OkHttpClient client = new OkHttpClient();
        HttpUrl httpUrl = new HttpUrl.Builder().scheme("https")
            .host("mapapi.cloud.huawei.com")
            .encodedPath("/mapApi/v1/mapService/getStaticMap")
            // 设置返回图片宽度为1024
            .addQueryParameter("width", "1024")
            // 设置返回图片高度为512
            .addQueryParameter("height", "512")
            // 地址信息,纬度:41.43206,经度:-81.38992
            .addQueryParameter("location", "41.43206,-81.38992")
            // 设置清晰度比较尺为1
            .addQueryParameter("scale", "1")
            // 设置缩放级别为5
            .addQueryParameter("zoom", "5")
            // 设置图片显示的语言为英语
            .addQueryParameter("language", "en")
            // logo样式描述
            .addQueryParameter("logo", "logoAnchor:bottomleft")
            // maker描述信息,纬度:41.43206,经度:-81.38992
            .addQueryParameter("markers", "{41.43206,-81.38992}")
            // maker描述信息,纬度:43.43206,经度:-85.38992
            .addQueryParameter("markers", "{43.43206,-85.38992}")
            // maker样式描述信息
            .addQueryParameter("markerStyles", "size:tiny|color:blue|label:p")
            // path描述信息,{纬度,经度}:{41.43206,-81.38992}|{43.43206,-85.38992}
            .addQueryParameter("path", "{41.43206,-81.38992}|{43.43206,-85.38992}")
            // path描述信息,样式为红色,{纬度,经度}:{41.43206,-81.38992}|{43.43206,-85.38992}|{39.43206,-83.38992}
            .addQueryParameter("path", "fillcolor:red|{41.43206,-81.38992}|{43.43206,-85.38992}|{39.43206,-83.38992}")
            // path样式描述信息
            .addQueryParameter("pathStyles", "weight:1|color:0x0000ff80|fillcolor:0x0000ff80")
            .build();
        String urlToSign = httpUrl.toString();
        // 签名密钥
        String secret = "xxx"; 
        String signature = sign(urlToSign, secret);       
        String url = urlToSign + "&signature=" + signature;
        
        Request request =                 
                new Request.Builder().url(ROOT_URL).addHeader("Authorization", "Bearer " + AT)
                        .get()
                        .build();

        Response response = client.newCall(request).execute();
        // 响应处理...
    }

    private String sign(String urlToSign, String secret)
        throws MalformedURLException, NoSuchAlgorithmException, InvalidKeyException {
        URL url = new URL(urlToSign);
        String canonicalUrl = url.getPath() + "?" + new CanonicalQueryString(url.getQuery()).toString();

        SecretKey secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(secretKey);
        byte[] sigBytes = mac.doFinal(canonicalUrl.getBytes());
        String signature = Base64.getEncoder().encodeToString(sigBytes);
        signature = signature.replace('+', '-');
        signature = signature.replace('/', '_');
        return signature;
    }

    static class CanonicalQueryString {
        private static final int INIT_BUFFER_SIZE = 128;

        /**
         * The constant PARAMETER_EQ.
         */
        public static final String PARAMETER_EQ = "=";

        /**
         * The constant PARAMETER_SEP.
         */
        public static final String PARAMETER_SEP = "&";

        private SortedMap<String, List<String>> params = new TreeMap<>();

        /**
         * Instantiates a new Canonical query string.
         *
         * @param queryString the query string
         */
        public CanonicalQueryString(String queryString) {
            if (queryString == null || queryString.length() == 0) {
                return;
            }

            for (String pair : queryString.split(PARAMETER_SEP)) {
                int idx = pair.indexOf(PARAMETER_EQ);
                if (idx != -1) {
                    String value = pair.substring(idx + 1);
                    if (value == null || value.length() == 0) {
                        continue;
                    }
                    String paramKey = pair.substring(0, idx);
                    List<String> values = params.computeIfAbsent(paramKey, key -> new ArrayList<>());
                    try {
                        values.add(URLDecoder.decode(value, "UTF-8"));
                    } catch (UnsupportedEncodingException e) {
                        // ignore
                    }
                }
            }
        }

        @Override
        public String toString() {
            StringBuilder sb = new StringBuilder(INIT_BUFFER_SIZE);
            for (SortedMap.Entry<String, List<String>> item : params.entrySet()) {
                String key = item.getKey();
                for (String value : item.getValue()) {
                    if (sb.length() > 0) {
                        sb.append(PARAMETER_SEP);
                    }
                    sb.append(key).append(PARAMETER_EQ).append(value);
                }
            }

            return sb.toString();
        }
    }
}
“API KEY认证”
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Base64;
import java.util.List;
import java.util.SortedMap;
import java.util.TreeMap;

import javax.crypto.Mac;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;

import okhttp3.HttpUrl;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

public class Demo {
    public static void main(String[] args) throws Exception {
        new Demo().getStaticMapWithUrlSignature();
    }

    private void getStaticMapWithUrlSignature() throws NoSuchAlgorithmException, InvalidKeyException, IOException {
        OkHttpClient client = new OkHttpClient();
        HttpUrl httpUrl = new HttpUrl.Builder().scheme("https")
            .host("mapapi.cloud.huawei.com")
            .encodedPath("/mapApi/v1/mapService/getStaticMap")
            // 设置返回图片宽度为1024
            .addQueryParameter("width", "1024")
            // 设置返回图片高度为512
            .addQueryParameter("height", "512")
            // 地址信息,纬度:41.43206,经度:-81.38992
            .addQueryParameter("location", "41.43206,-81.38992")
            // 设置清晰度比较尺为1
            .addQueryParameter("scale", "1")
            // 设置缩放级别为5
            .addQueryParameter("zoom", "5")
            // 设置图片显示的语言为英语
            .addQueryParameter("language", "en")
            // logo样式描述
            .addQueryParameter("logo", "logoAnchor:bottomleft")
            // maker描述信息,纬度:41.43206,经度:-81.38992
            .addQueryParameter("markers", "{41.43206,-81.38992}")
            // maker描述信息,纬度:43.43206,经度:-85.38992
            .addQueryParameter("markers", "{43.43206,-85.38992}")
            // maker样式描述信息
            .addQueryParameter("markerStyles", "size:tiny|color:blue|label:p")
            // path描述信息,{纬度,经度}:{41.43206,-81.38992}|{43.43206,-85.38992}
            .addQueryParameter("path", "{41.43206,-81.38992}|{43.43206,-85.38992}")
            // path描述信息,样式为红色,{纬度,经度}:{41.43206,-81.38992}|{43.43206,-85.38992}|{39.43206,-83.38992}
            .addQueryParameter("path", "fillcolor:red|{41.43206,-81.38992}|{43.43206,-85.38992}|{39.43206,-83.38992}")
            // path样式描述信息
            .addQueryParameter("pathStyles", "weight:1|color:0x0000ff80|fillcolor:0x0000ff80")
            .build();
        String urlToSign = httpUrl.toString();
        // 签名密钥
        String secret = "xxx"; 
        String signature = sign(urlToSign, secret);
        // URLEncoder.encode编码后的API密钥
        String encodedApiKey = "xxx"; 
        String url = urlToSign + "&key=" + encodedApiKey + "&signature=" + signature;
        Request request = new Request.Builder().url(url).get().build();

        Response response = client.newCall(request).execute();
        // 响应处理...
    }

    private String sign(String urlToSign, String secret)
        throws MalformedURLException, NoSuchAlgorithmException, InvalidKeyException {
        URL url = new URL(urlToSign);
        String canonicalUrl = url.getPath() + "?" + new CanonicalQueryString(url.getQuery()).toString();

        SecretKey secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(secretKey);
        byte[] sigBytes = mac.doFinal(canonicalUrl.getBytes());
        String signature = Base64.getEncoder().encodeToString(sigBytes);
        signature = signature.replace('+', '-');
        signature = signature.replace('/', '_');
        return signature;
    }

    static class CanonicalQueryString {
        private static final int INIT_BUFFER_SIZE = 128;

        /**
         * The constant PARAMETER_EQ.
         */
        public static final String PARAMETER_EQ = "=";

        /**
         * The constant PARAMETER_SEP.
         */
        public static final String PARAMETER_SEP = "&";

        private SortedMap<String, List<String>> params = new TreeMap<>();

        /**
         * Instantiates a new Canonical query string.
         *
         * @param queryString the query string
         */
        public CanonicalQueryString(String queryString) {
            if (queryString == null || queryString.length() == 0) {
                return;
            }

            for (String pair : queryString.split(PARAMETER_SEP)) {
                int idx = pair.indexOf(PARAMETER_EQ);
                if (idx != -1) {
                    String value = pair.substring(idx + 1);
                    if (value == null || value.length() == 0) {
                        continue;
                    }
                    String paramKey = pair.substring(0, idx);
                    List<String> values = params.computeIfAbsent(paramKey, key -> new ArrayList<>());
                    try {
                        values.add(URLDecoder.decode(value, "UTF-8"));
                    } catch (UnsupportedEncodingException e) {
                        // ignore
                    }
                }
            }
        }

        @Override
        public String toString() {
            StringBuilder sb = new StringBuilder(INIT_BUFFER_SIZE);
            for (SortedMap.Entry<String, List<String>> item : params.entrySet()) {
                String key = item.getKey();
                for (String value : item.getValue()) {
                    if (sb.length() > 0) {
                        sb.append(PARAMETER_SEP);
                    }
                    sb.append(key).append(PARAMETER_EQ).append(value);
                }
            }

            return sb.toString();
        }
    }
}
图5 获取静态图