靜態(tài)地圖 API 開發(fā)人員指南.docx

靜態(tài)地圖 API 開發(fā)人員指南歡迎閱讀 Google 靜態(tài)地圖 API 的開發(fā)人員文檔！通過 Google 靜態(tài)地圖 API，您不需要使用 JavaScript 或加載任何動(dòng)態(tài)頁面，便可將 Google 地圖圖像嵌入到自己的網(wǎng)頁中。Google 靜態(tài)地圖服務(wù)會(huì)根據(jù)通過標(biāo)準(zhǔn) HTTP 請(qǐng)求發(fā)送的網(wǎng)址參數(shù)來創(chuàng)建您的地圖，并將地圖以您可以在網(wǎng)頁上顯示的圖像形式返回。Google 靜態(tài)地圖 API 需要地圖 API 密鑰。如果尚未注冊(cè)地圖 API 密鑰，請(qǐng)注冊(cè)一個(gè)免費(fèi)的 API 密鑰。新！Google 靜態(tài)地圖 API 現(xiàn)在具有衛(wèi)星和地形圖塊功能！快速示例以下示例包含靜態(tài)地圖圖像的網(wǎng)址，如下所示：# Note that this URL wraps at the character.# You can copy the URL from the image below, however.# For clarity, we dont write the actual API key in use.#/staticmap?center=40.714728,-73.998672&zoom=14&size=512x512&maptype=mobile&markers=39.949328,116.3875,blues%7C39.949328,116.3775,greeng%7C39.943028,116.3975,redc&key=MAPS_API_KEY&sensor=false請(qǐng)注意，您無需進(jìn)行任何“特殊”操作便可在地圖上顯示此圖像。不需要 JavaScript。只需創(chuàng)建一個(gè)網(wǎng)址并將其放入 標(biāo)簽中。您可以將 Google 靜態(tài)地圖放在可放置圖像的網(wǎng)頁上的任何位置。目錄1. 受眾2. 使用限制3. 概覽4. 網(wǎng)址參數(shù)5. 參數(shù)的用法 o 指定位置 經(jīng)度和緯度 地址解析o 縮放級(jí)別o 圖像大小o 視口o 圖像格式o 地圖類型o 添加標(biāo)記 標(biāo)記描述符 使用標(biāo)記隱式定位地圖o 靜態(tài)地圖路徑 路徑屬性 指定路徑點(diǎn)6. 更多信息讀者本文檔適用于希望在網(wǎng)頁中包含 Google 靜態(tài)地圖 API 圖像的網(wǎng)站和手機(jī)開發(fā)人員。它對(duì)使用有關(guān)可用參數(shù)的 API 和參考材料進(jìn)行了介紹。使用限制使用靜態(tài)地圖 API 需要注冊(cè)一個(gè)免費(fèi)的地圖 API 密鑰。地圖 API 密鑰允許您使用靜態(tài)地圖 API 和標(biāo)準(zhǔn)地圖 API。使用 Google 靜態(tài)地圖 API 還需遵從每位查看者每天的唯一（不同）圖像請(qǐng)求不超過 1000 次的查詢限制。由于此限制是按“查看者”而非“關(guān)鍵字”制訂的配額，因此大多數(shù)開發(fā)人員并不需要為超過其配額而擔(dān)心。此外，請(qǐng)注意，一般情況下，對(duì)相同圖像的請(qǐng)求，除了第一次，其他請(qǐng)求并不計(jì)入該限制。如果用戶超出以上的禁止限制，則將顯示以下圖像，指示超出了配額：強(qiáng)制執(zhí)行此限制是為了防止濫用和/或重復(fù)使用靜態(tài)地圖 API。以后可能對(duì)此限制進(jìn)行更改，而無需另行通知。如果超過了 24 小時(shí)的限制或?yàn)E用此服務(wù)，靜態(tài)地圖 API 會(huì)臨時(shí)停止運(yùn)行。如果您繼續(xù)無視這個(gè)限制，將會(huì)阻止您對(duì)靜態(tài)地圖 API 的訪問。概述Google 靜態(tài)地圖 API 通過網(wǎng)址返回圖像（GIF、PNG 或 JPEG）來響應(yīng) HTTP 請(qǐng)求。您可以為每個(gè)請(qǐng)求指定地圖的位置、圖像的大小、縮放級(jí)別、地圖的類型以及可選標(biāo)記在地圖各個(gè)位置上的放置。此外，您還可以使用字母字符為您的標(biāo)記制作標(biāo)簽，以便在“關(guān)鍵字”中引用這些標(biāo)記。將靜態(tài)地圖 API 圖像嵌入 標(biāo)簽的 src 屬性內(nèi)的網(wǎng)頁上。當(dāng)顯示網(wǎng)頁時(shí)，瀏覽器從靜態(tài)地圖 API 請(qǐng)求圖像，并顯示在圖像位置內(nèi)。本文檔介紹了靜態(tài)地圖 API 網(wǎng)址的所需格式和可用參數(shù)。還提供了一些指定網(wǎng)址的提示和技巧。網(wǎng)址參數(shù)Google 靜態(tài)地圖 API 網(wǎng)址必須為以下形式：/staticmap?parameters有些參數(shù)是必需的，而有些參數(shù)則是可選的。根據(jù) HTTP 請(qǐng)求的標(biāo)準(zhǔn)，所有參數(shù)均使用 & (&) 字符分隔。參數(shù)列表及參數(shù)的可能值枚舉如下。靜態(tài)地圖 API 使用以下網(wǎng)址參數(shù)定義地圖圖像： center（不顯示標(biāo)記時(shí)為必需）定義地圖的中心，到地圖各邊緣的距離相等。此參數(shù)采用一個(gè)用逗號(hào)分隔的 經(jīng)度,緯度 對(duì)（例如，40.714728,-73.998672）來標(biāo)識(shí)地球表面的唯一位置。有關(guān)詳細(xì)信息，請(qǐng)參見下面的經(jīng)度和緯度。 zoom （不顯示標(biāo)記時(shí)為必需）定義地圖的縮放級(jí)別，縮放級(jí)別確定地圖放大的級(jí)別。此參數(shù)根據(jù)所需的區(qū)域縮放級(jí)別來采用數(shù)字值。有關(guān)更多信息，請(qǐng)參見下面的縮放級(jí)別。 size（必需）定義地圖圖像的矩形尺寸。此參數(shù)采用 valuexvalue 形式的字符串，其中先表示水平像素，再表示垂直像素。例如，500x400 定義了一幅寬為 500 像素、高為 400 像素的地圖。如果您創(chuàng)建一幅寬為 100 像素或更小的靜態(tài)地圖，“由 Google 強(qiáng)力驅(qū)動(dòng)”徽標(biāo)的大小會(huì)自動(dòng)縮小。 format（可選）定義生成的圖像的格式。默認(rèn)情況下，靜態(tài)地圖 API 創(chuàng)建 GIF 圖像。有若干種可能的格式，包括 GIF、JPEG 和 PNG 類型。使用哪種格式取決于您想要顯示圖像的方式。JPEG 通常提供更大程度的壓縮，而 GIF 和 PNG 提供更多細(xì)節(jié)。有關(guān)詳細(xì)信息，請(qǐng)參見圖像格式。 maptype（可選）定義要構(gòu)造的地圖類型。有若干種可能的地圖類型值，包括 satellite、terrain、hybrid 和 mobile。有關(guān)更多信息，請(qǐng)參見下面的靜態(tài)地圖 API 地圖類型。 markers（可選）定義要在指定位置附加到圖像的一個(gè)或多個(gè)標(biāo)記。此參數(shù)采用由管道字符 (|) 分隔的標(biāo)記定義的字符串。請(qǐng)注意，如果為地圖提供標(biāo)記，就無需指定（通常情況下必需的）center 和 zoom 參數(shù)。有關(guān)更多信息，請(qǐng)參見下面的靜態(tài)地圖標(biāo)記。 path（可選）定義要在指定位置覆蓋在圖像上的單條路徑，其由兩個(gè)或兩個(gè)以上的連接點(diǎn)組成。此參數(shù)采用由管道字符 (|) 分隔的點(diǎn)定義的字符串。請(qǐng)注意，如果為地圖提供標(biāo)記，就無需指定（通常情況下必需的）center 和 zoom 參數(shù)。有關(guān)詳細(xì)信息，請(qǐng)參見下面的靜態(tài)地圖路徑。 span（可選）定義地圖圖像的最小“視口”，以成對(duì)的緯度和經(jīng)度表示。靜態(tài)地圖服務(wù)采用該值并生成適當(dāng)縮放級(jí)別的地圖，以包含距地圖中心點(diǎn)的所提供全部的 span 值。請(qǐng)注意，生成的地圖可能包含在經(jīng)度或緯度上更大的邊界，這取決于地圖的矩形尺寸。如果指定了 zoom，則會(huì)忽略 span。 frame（可選）指定生成的圖像應(yīng)由藍(lán)色的邊框框起來?？蚣苡?5 像素寬，不透明度為 55% 的藍(lán)色邊框組成。 hl（可選）定義用于在地圖圖塊上顯示標(biāo)簽的語言。請(qǐng)注意，該參數(shù)僅支持部分國(guó)家/地區(qū)圖塊；如果請(qǐng)求的指定語言不支持圖塊集，則將為該圖塊集使用默認(rèn)的語言。 key（必需）標(biāo)識(shí)生成此網(wǎng)址請(qǐng)求的域的地圖API 密鑰。如果沒有地圖 API 密鑰，可以注冊(cè)一個(gè)免費(fèi)的地圖 API 密鑰。 sensor（必需）指定請(qǐng)求靜態(tài)地圖的應(yīng)用程序是否使用傳感器來確定用戶的位置。對(duì)于所有靜態(tài)地圖請(qǐng)求，此參數(shù)都是必需的。有關(guān)詳細(xì)信息，請(qǐng)參見下面的傳感器。參數(shù)的用法靜態(tài)地圖 API 相對(duì)來說易于使用，因?yàn)樗话粋€(gè)參數(shù)網(wǎng)址。此部分介紹怎樣使用這些參數(shù)構(gòu)造您的網(wǎng)址。指定位置靜態(tài)地圖 API 必須能夠精確標(biāo)識(shí)地圖上的位置，目的在于使地圖處于正確的位置（使用 center 參數(shù)）和/或?qū)⑷魏慰蛇x地標(biāo)放置到地圖的各個(gè)位置上（使用markers參數(shù)）。靜態(tài)地圖 API 使用經(jīng)緯度值指定這些位置。這些值共同標(biāo)識(shí)“地址解析”位置。如果您的設(shè)備使用“傳感器”（例如 GPS 設(shè)備）來確定某個(gè)設(shè)備或用戶的位置，您還必須在您的靜態(tài)地圖 API 請(qǐng)求網(wǎng)址內(nèi)傳遞 sensor=true。如果您的應(yīng)用程序不使用傳感器，則傳遞 sensor=false。經(jīng)度和緯度使用逗號(hào)分隔的文本字符串內(nèi)的數(shù)字定義經(jīng)度和緯度，精確到 6 位小數(shù)。例如，“40.714728，-73.998672”是有效的地址解析值。精確到 6 位小數(shù)之后的部分將被忽略。經(jīng)度值基于其到英國(guó)格林威治（本初子午線所在地）的距離。由于格林威治位于緯度 51.477222，我們可以輸入 center 值 51.477222,0 來使地圖以格林威治為中心：經(jīng)緯度值必須與地球表面的有效位置對(duì)應(yīng)。緯度可以采用 -90 和 90 之間的任意值，而經(jīng)度值則可采用 -180 和 180 之間的任意值。如果指定了無效的緯度或經(jīng)度值，您的請(qǐng)求將作為錯(cuò)誤請(qǐng)求被拒絕。地址解析許多人不使用經(jīng)度和緯度，而是使用“地址”來表示位置。將地址轉(zhuǎn)換為地理點(diǎn)的過程稱為“地址解析”，將在 Google 地圖 API 服務(wù)部分中詳細(xì)討論。請(qǐng)注意，要直接使用地址解析服務(wù)，需要使用地圖 API 密鑰。除了這個(gè)地址解析服務(wù)之外，您也可以使用其他服務(wù)（包括 Google 地圖本身）來獲取經(jīng)地址解析后的經(jīng)緯度值。例如，您可以將某個(gè)地址輸入到 Google 地圖，并通過單擊地圖右上方的鏈接到該頁面來確定其經(jīng)地址解析后的位置。將顯示一個(gè)彈出式對(duì)話框，對(duì)話框內(nèi)可復(fù)制的網(wǎng)址。如果將該網(wǎng)址復(fù)制到瀏覽器中，您便可以查找 ll 參數(shù)中包含的地址解析值。縮放級(jí)別Google 地圖上的地圖具有整數(shù)“縮放級(jí)別”，可定義當(dāng)前視圖的分辨率。普通地圖視圖中，可以使用 0（最低縮放級(jí)別，在地圖上可以看到整個(gè)世界）到 19（最高縮放級(jí)別，可以看到每個(gè)建筑物）之間的縮放級(jí)別。Google 地圖將縮放級(jí)別 0 設(shè)為包含整個(gè)地球。隨后的每個(gè)縮放級(jí)別在水平和垂直尺寸上使精確度加倍。Google 地圖 API 文檔中提供了有關(guān)怎樣執(zhí)行此操作的詳細(xì)信息。注意：并非地球上的所有位置都會(huì)顯示所有的縮放級(jí)別?？s放級(jí)別根據(jù)位置的不同而有所不同，因?yàn)榈厍蛏夏承┑貐^(qū)的數(shù)據(jù)與其他地區(qū)相比更加細(xì)化。如果發(fā)送了并不存在任何地圖圖塊的縮放級(jí)別請(qǐng)求，靜態(tài)地圖 API 將轉(zhuǎn)而返回黑色圖像。下面的示例請(qǐng)求了兩幅曼哈頓地圖，center 值相同，但縮放級(jí)別分別為 12 和 14：/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=MAPS_API_KEY&sensor=true_or_false/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=MAPS_API_KEY&sensor=true_or_false圖像大小可以檢索的最大圖像大小為 640 x 640 像素。size 參數(shù)采用具有兩個(gè)值的字符串，這兩個(gè)值由 x 字符分隔。640x640 是所允許的最大圖像大小。請(qǐng)注意，center 參數(shù)與 size 參數(shù)相結(jié)合可隱式定義地圖圖像的覆蓋區(qū)域。下面的示例請(qǐng)求地球赤道上的某個(gè)“塊”（縮放級(jí)別為 1）：/staticmap?center=0,0&zoom=1&size=400x50&key=MAPS_API_KEY&sensor=true_or_false以下示例請(qǐng)求 100 x 100 像素大小的小型地圖，以相同的區(qū)域?yàn)橹行摹Ｕ?qǐng)注意較小的 Google 徽標(biāo)：視口圖像可能通過傳遞 span 參數(shù)指定一個(gè)“視口”（按緯度和經(jīng)度值定義，以度為單位）來顯示提供的中心點(diǎn)周圍的地區(qū)。以這種方式定義最大視口免去了指定確切縮放級(jí)別的必要。靜態(tài)地圖服務(wù)將 span 參數(shù)與 size 參數(shù)配合使用來構(gòu)建適當(dāng)縮放級(jí)別的地圖，其中至少包括指定的視口限制。以下示例請(qǐng)求一個(gè)方形地圖，以 0 度經(jīng)度和 0 度緯度為中心，寬度和高度為 20 度：/staticmap?center=0,0&span=20,20&size=512x512&key=MAPS_API_KEY&sensor=true_or_false以下示例請(qǐng)求一個(gè)以曼哈頓為中心的地圖，在兩個(gè)方向顯示 1 度的弧度。請(qǐng)注意，因?yàn)樵摰貓D水平形成，在水平方向擴(kuò)展 4 度，因此可以在垂直方向最少擴(kuò)展 1 度。/staticmap?center=40.714728,-73.998672&span=1,1&size=512x128&key=MAPS_API_KEY&sensor=true_or_false圖像格式可以以若干種常見網(wǎng)絡(luò)圖形格式返回圖像：GIF、JPEG 和 PNG。format 參數(shù)采用以下值之一： gif（默認(rèn)）指定 GIF 格式。 jpg 指定 JPEG 壓縮格式。 jpg-baseline 指定非漸進(jìn)式 JPEG 壓縮格式。 png8 指定 8 位 PNG 格式。 png32 指定 32 位 PNG 格式。jpg 和 jpg-baseline 通常提供最小的圖像大小，但是這是通過“有損”壓縮而實(shí)現(xiàn)，這將降低圖像的質(zhì)量。gif、png8 和 png32 提供無損壓縮。大多數(shù) JPEG 圖像都是漸進(jìn)式，這意味著它們先加載“較粗糙的”圖像，再隨著更多數(shù)據(jù)的傳入而優(yōu)化圖像分辨率。這使圖像在網(wǎng)頁中能夠迅速加載，是當(dāng)前最普及的 JPEG 應(yīng)用。但是，JPEG 的部分使用（尤其是打?。┮蠓菨u進(jìn)式（基線）圖像。在這種情況下，您可能想使用非漸進(jìn)式的 jpg-baseline 格式。地圖類型Google 靜態(tài)地圖 API 以若干種格式創(chuàng)建地圖，如下所列： roadmap（默認(rèn)）指定標(biāo)準(zhǔn)路線圖圖像，如 Google 地圖網(wǎng)站通常所示。如果未指定 maptype 值，默認(rèn)情況下，靜態(tài)地圖 API 會(huì)使用 roadmap 圖塊。 mobile 指定移動(dòng)設(shè)備的路線圖地圖圖像，它包含更多的特征和文本字體，從而能夠以高分辨率在移動(dòng)設(shè)備的小屏幕上方便地進(jìn)行查看。 satellite 指定衛(wèi)星圖像。 terrain 指定自然地形地圖圖像，顯示地形和植被。 hybrid 指定衛(wèi)星和路線圖的混合圖像，在衛(wèi)星圖像上顯示主要街道和地址名稱的透明層。您可以在以下代碼示例中查看路線圖和移動(dòng)設(shè)備這兩種類型之間的區(qū)別。請(qǐng)注意，這些地圖也有 frame=true。/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=MAPS_API_KEY&sensor=true_or_false/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=mobile&key=MAPS_API_KEY&sensor=true_or_false以下示例顯示了衛(wèi)星地圖類型和地形地圖類型：/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=MAPS_API_KEY&sensor=true_or_false/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=MAPS_API_KEY&sensor=true_or_false標(biāo)記markers 參數(shù)定義要添加到地圖圖像中的一個(gè)或多個(gè)標(biāo)記的集合。此參數(shù)是一個(gè)由賦值集合定義的多達(dá) 50 個(gè)標(biāo)記的列表： markers=markerDescriptor1|markerDescriptor2|markerDescriptor3|. 等。請(qǐng)注意，標(biāo)記描述符使用管道字符 (|) 相互隔開。（注意：如果正在對(duì)網(wǎng)址進(jìn)行編碼，管道字符在 ASCII 中也顯示為 %7C。）標(biāo)記描述符每個(gè)標(biāo)記描述符都包含一個(gè)字符串，用于定義放置標(biāo)記的位置和顯示標(biāo)記時(shí)使用的可視屬性。這些字符串包含以下變量值： latitude（必需）指定緯度值，精確到 6 位小數(shù)。 longitude（必需）指定經(jīng)度值，精確到 6 位小數(shù)。 size（可選）指定集合 tiny, mid, small 中的標(biāo)記大小。如果未設(shè)置 size 參數(shù)，標(biāo)記將以其默認(rèn)（常規(guī)）大小顯示。 color（可選）指定集合 black, brown, green, purple, yellow, blue, gray, orange, red, white 中的一種顏色。 alphanumeric-character（可選）指定集合 a-z, 0-9 中的一個(gè)小寫字母數(shù)字字符。請(qǐng)注意，顯示 alphanumeric-character 參數(shù)時(shí)僅能使用默認(rèn)和 mid 大小的標(biāo)記。tiny 和 small 標(biāo)記無法顯示字母數(shù)字字符。緯度和經(jīng)度值定義標(biāo)記在地圖上的位置。如果位置在地圖之外，該標(biāo)記將不會(huì)顯示在構(gòu)建的圖像上。大小、顏色和字母數(shù)字字符值可以定義標(biāo)記的可視外觀。如果未指定大小值，標(biāo)記會(huì)以其默認(rèn)（常規(guī)）大小顯示。此外，只有常規(guī)大小的標(biāo)記才能顯示字母數(shù)字字符。如果未指定值（或指定了錯(cuò)誤的值），則標(biāo)記會(huì)顯示為默認(rèn)的帶點(diǎn)紅色標(biāo)記。示例標(biāo)記聲明的格式為 latitude,longitude,sizecoloralphanumeric-character。請(qǐng)?zhí)貏e注意，字符串的大小、顏色和字母數(shù)字字符值不用逗號(hào)隔開。樣本標(biāo)記聲明如下所示。markers=39.949328,116.3875,blues|40.711614,-74.012318,tinygreen|40.713504,-74.005607,midyellowc&key=MAPS_API_KEY&sensor=true_or_false此 markers 參數(shù)定義三個(gè)標(biāo)記（用“|”字符分隔）：40.702147,-74.015794 處標(biāo)為“S”的一個(gè)藍(lán)色標(biāo)記，40.711614,-74.012318 處的一個(gè)小型綠色標(biāo)記，以及 40.713504,-74.005607（市政廳）處標(biāo)為“C”的一個(gè)中等大小紅色標(biāo)記。以下示例中顯示了這些標(biāo)記：使用標(biāo)記隱式定位地圖通常，您需要指定 center 和 zoom 網(wǎng)址參數(shù)來定義生成的地圖的位置和縮放級(jí)別。但是，如果提供了 markers 參數(shù)，您也可以改用靜態(tài)地圖 API 來隱式確定正確的中心和縮放級(jí)別，具體取決于對(duì)這些標(biāo)記位置的估算。如果提供兩個(gè)或兩個(gè)以上的標(biāo)記，靜態(tài)地圖 API 將確定適當(dāng)?shù)闹行暮涂s放級(jí)別，從而提供足夠的邊距以顯示 markers 參數(shù)中包含的標(biāo)記。下面的示例包含與上面顯示的標(biāo)記相同的標(biāo)記，但刪除了 center 和 zoom 參數(shù)，使地圖中心更接近兩個(gè)目標(biāo)標(biāo)記的位置。靜態(tài)地圖路徑path 參數(shù)定義要在地圖圖像上覆蓋的一條或多條路徑的集合。此參數(shù)是一個(gè)由賦值集合定義的路徑列表：path=pathColorType:pathColorValue,weight:pathWeight|pathPoint1|pathPoint2|pathPoint3|. 等。請(qǐng)注意，路徑點(diǎn)使用管道字符 (|) 相互隔開。（如果對(duì)網(wǎng)址進(jìn)行編碼，管道字符在 ASCII 中也顯示為 %7C。）路徑屬性每個(gè) path 參數(shù)的開頭都可能是指定路徑屬性的可選字符串，由“pathColorType”和該類型的值組成（使用冒號(hào)分隔）。如果需要默認(rèn)的路徑屬性，可能忽略路徑描述符中的路徑屬性前綴；在本例中，路徑描述符的第一個(gè)參數(shù)描述路徑聲明中的第一個(gè)點(diǎn)。（請(qǐng)參見下面的路徑點(diǎn)。）有兩種可能的“pathColorType”： rgb 指定標(biāo)準(zhǔn)的 RGB 顏色方案，使用 0xffffff 形式的 24 位十六進(jìn)制值顏色