靜態(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 請求發(fā)送的網(wǎng)址參數(shù)來創(chuàng)建您的地圖，并將地圖以您可以在網(wǎng)頁上顯示的圖像形式返回。Google 靜態(tài)地圖 API 需要地圖 API 密鑰。如果尚未注冊地圖 API 密鑰，請注冊一個(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請注意，您無需進(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 縮放級別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ā)人員。它對使用有關(guān)可用參數(shù)的 API 和參考材料進(jìn)行了介紹。使用限制使用靜態(tài)地圖 API 需要注冊一個(gè)免費(fèi)的地圖 API 密鑰。地圖 API 密鑰允許您使用靜態(tài)地圖 API 和標(biāo)準(zhǔn)地圖 API。使用 Google 靜態(tài)地圖 API 還需遵從每位查看者每天的唯一（不同）圖像請求不超過 1000 次的查詢限制。由于此限制是按“查看者”而非“關(guān)鍵字”制訂的配額，因此大多數(shù)開發(fā)人員并不需要為超過其配額而擔(dān)心。此外，請注意，一般情況下，對相同圖像的請求，除了第一次，其他請求并不計(jì)入該限制。如果用戶超出以上的禁止限制，則將顯示以下圖像，指示超出了配額：強(qiáng)制執(zhí)行此限制是為了防止濫用和/或重復(fù)使用靜態(tài)地圖 API。以后可能對此限制進(jìn)行更改，而無需另行通知。如果超過了 24 小時(shí)的限制或?yàn)E用此服務(wù)，靜態(tài)地圖 API 會(huì)臨時(shí)停止運(yùn)行。如果您繼續(xù)無視這個(gè)限制，將會(huì)阻止您對靜態(tài)地圖 API 的訪問。概述Google 靜態(tài)地圖 API 通過網(wǎng)址返回圖像（GIF、PNG 或 JPEG）來響應(yīng) HTTP 請求。您可以為每個(gè)請求指定地圖的位置、圖像的大小、縮放級別、地圖的類型以及可選標(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 請求圖像，并顯示在圖像位置內(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 請求的標(biāo)準(zhǔn)，所有參數(shù)均使用 & (&) 字符分隔。參數(shù)列表及參數(shù)的可能值枚舉如下。靜態(tài)地圖 API 使用以下網(wǎng)址參數(shù)定義地圖圖像： center（不顯示標(biāo)記時(shí)為必需）定義地圖的中心，到地圖各邊緣的距離相等。此參數(shù)采用一個(gè)用逗號分隔的 經(jīng)度,緯度 對（例如，40.714728,-73.998672）來標(biāo)識地球表面的唯一位置。有關(guān)詳細(xì)信息，請參見下面的經(jīng)度和緯度。 zoom （不顯示標(biāo)記時(shí)為必需）定義地圖的縮放級別，縮放級別確定地圖放大的級別。此參數(shù)根據(jù)所需的區(qū)域縮放級別來采用數(shù)字值。有關(guān)更多信息，請參見下面的縮放級別。 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ì)信息，請參見圖像格式。 maptype（可選）定義要構(gòu)造的地圖類型。有若干種可能的地圖類型值，包括 satellite、terrain、hybrid 和 mobile。有關(guān)更多信息，請參見下面的靜態(tài)地圖 API 地圖類型。 markers（可選）定義要在指定位置附加到圖像的一個(gè)或多個(gè)標(biāo)記。此參數(shù)采用由管道字符 (|) 分隔的標(biāo)記定義的字符串。請注意，如果為地圖提供標(biāo)記，就無需指定（通常情況下必需的）center 和 zoom 參數(shù)。有關(guān)更多信息，請參見下面的靜態(tài)地圖標(biāo)記。 path（可選）定義要在指定位置覆蓋在圖像上的單條路徑，其由兩個(gè)或兩個(gè)以上的連接點(diǎn)組成。此參數(shù)采用由管道字符 (|) 分隔的點(diǎn)定義的字符串。請注意，如果為地圖提供標(biāo)記，就無需指定（通常情況下必需的）center 和 zoom 參數(shù)。有關(guān)詳細(xì)信息，請參見下面的靜態(tài)地圖路徑。 span（可選）定義地圖圖像的最小“視口”，以成對的緯度和經(jīng)度表示。靜態(tài)地圖服務(wù)采用該值并生成適當(dāng)縮放級別的地圖，以包含距地圖中心點(diǎn)的所提供全部的 span 值。請注意，生成的地圖可能包含在經(jīng)度或緯度上更大的邊界，這取決于地圖的矩形尺寸。如果指定了 zoom，則會(huì)忽略 span。 frame（可選）指定生成的圖像應(yīng)由藍(lán)色的邊框框起來?？蚣苡?5 像素寬，不透明度為 55% 的藍(lán)色邊框組成。 hl（可選）定義用于在地圖圖塊上顯示標(biāo)簽的語言。請注意，該參數(shù)僅支持部分國家/地區(qū)圖塊；如果請求的指定語言不支持圖塊集，則將為該圖塊集使用默認(rèn)的語言。 key（必需）標(biāo)識生成此網(wǎng)址請求的域的地圖API 密鑰。如果沒有地圖 API 密鑰，可以注冊一個(gè)免費(fèi)的地圖 API 密鑰。 sensor（必需）指定請求靜態(tài)地圖的應(yīng)用程序是否使用傳感器來確定用戶的位置。對于所有靜態(tài)地圖請求，此參數(shù)都是必需的。有關(guān)詳細(xì)信息，請參見下面的傳感器。參數(shù)的用法靜態(tài)地圖 API 相對來說易于使用，因?yàn)樗话粋€(gè)參數(shù)網(wǎng)址。此部分介紹怎樣使用這些參數(shù)構(gòu)造您的網(wǎng)址。指定位置靜態(tài)地圖 API 必須能夠精確標(biāo)識地圖上的位置，目的在于使地圖處于正確的位置（使用 center 參數(shù)）和/或?qū)⑷魏慰蛇x地標(biāo)放置到地圖的各個(gè)位置上（使用markers參數(shù)）。靜態(tài)地圖 API 使用經(jīng)緯度值指定這些位置。這些值共同標(biāo)識“地址解析”位置。如果您的設(shè)備使用“傳感器”（例如 GPS 設(shè)備）來確定某個(gè)設(shè)備或用戶的位置，您還必須在您的靜態(tài)地圖 API 請求網(wǎng)址內(nèi)傳遞 sensor=true。如果您的應(yīng)用程序不使用傳感器，則傳遞 sensor=false。經(jīng)度和緯度使用逗號分隔的文本字符串內(nèi)的數(shù)字定義經(jīng)度和緯度，精確到 6 位小數(shù)。例如，“40.714728，-73.998672”是有效的地址解析值。精確到 6 位小數(shù)之后的部分將被忽略。經(jīng)度值基于其到英國格林威治（本初子午線所在地）的距離。由于格林威治位于緯度 51.477222，我們可以輸入 center 值 51.477222,0 來使地圖以格林威治為中心：經(jīng)緯度值必須與地球表面的有效位置對應(yīng)。緯度可以采用 -90 和 90 之間的任意值，而經(jīng)度值則可采用 -180 和 180 之間的任意值。如果指定了無效的緯度或經(jīng)度值，您的請求將作為錯(cuò)誤請求被拒絕。地址解析許多人不使用經(jīng)度和緯度，而是使用“地址”來表示位置。將地址轉(zhuǎn)換為地理點(diǎn)的過程稱為“地址解析”，將在 Google 地圖 API 服務(wù)部分中詳細(xì)討論。請注意，要直接使用地址解析服務(wù)，需要使用地圖 API 密鑰。除了這個(gè)地址解析服務(wù)之外，您也可以使用其他服務(wù)（包括 Google 地圖本身）來獲取經(jīng)地址解析后的經(jīng)緯度值。例如，您可以將某個(gè)地址輸入到 Google 地圖，并通過單擊地圖右上方的鏈接到該頁面來確定其經(jīng)地址解析后的位置。將顯示一個(gè)彈出式對話框，對話框內(nèi)可復(fù)制的網(wǎng)址。如果將該網(wǎng)址復(fù)制到瀏覽器中，您便可以查找 ll 參數(shù)中包含的地址解析值?？s放級別Google 地圖上的地圖具有整數(shù)“縮放級別”，可定義當(dāng)前視圖的分辨率。普通地圖視圖中，可以使用 0（最低縮放級別，在地圖上可以看到整個(gè)世界）到 19（最高縮放級別，可以看到每個(gè)建筑物）之間的縮放級別。Google 地圖將縮放級別 0 設(shè)為包含整個(gè)地球。隨后的每個(gè)縮放級別在水平和垂直尺寸上使精確度加倍。Google 地圖 API 文檔中提供了有關(guān)怎樣執(zhí)行此操作的詳細(xì)信息。注意：并非地球上的所有位置都會(huì)顯示所有的縮放級別?？s放級別根據(jù)位置的不同而有所不同，因?yàn)榈厍蛏夏承┑貐^(qū)的數(shù)據(jù)與其他地區(qū)相比更加細(xì)化。如果發(fā)送了并不存在任何地圖圖塊的縮放級別請求，靜態(tài)地圖 API 將轉(zhuǎn)而返回黑色圖像。下面的示例請求了兩幅曼哈頓地圖，center 值相同，但縮放級別分別為 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 是所允許的最大圖像大小。請注意，center 參數(shù)與 size 參數(shù)相結(jié)合可隱式定義地圖圖像的覆蓋區(qū)域。下面的示例請求地球赤道上的某個(gè)“塊”（縮放級別為 1）：/staticmap?center=0,0&zoom=1&size=400x50&key=MAPS_API_KEY&sensor=true_or_false以下示例請求 100 x 100 像素大小的小型地圖，以相同的區(qū)域?yàn)橹行?。請注意較小的 Google 徽標(biāo)：視口圖像可能通過傳遞 span 參數(shù)指定一個(gè)“視口”（按緯度和經(jīng)度值定義，以度為單位）來顯示提供的中心點(diǎn)周圍的地區(qū)。以這種方式定義最大視口免去了指定確切縮放級別的必要。靜態(tài)地圖服務(wù)將 span 參數(shù)與 size 參數(shù)配合使用來構(gòu)建適當(dāng)縮放級別的地圖，其中至少包括指定的視口限制。以下示例請求一個(gè)方形地圖，以 0 度經(jīng)度和 0 度緯度為中心，寬度和高度為 20 度：/staticmap?center=0,0&span=20,20&size=512x512&key=MAPS_API_KEY&sensor=true_or_false以下示例請求一個(gè)以曼哈頓為中心的地圖，在兩個(gè)方向顯示 1 度的弧度。請注意，因?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ū)別。請注意，這些地圖也有 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|. 等。請注意，標(biāo)記描述符使用管道字符 (|) 相互隔開。（注意：如果正在對網(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ù)字字符。請注意，顯示 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。請?zhí)貏e注意，字符串的大小、顏色和字母數(shù)字字符值不用逗號隔開。樣本標(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ù)來定義生成的地圖的位置和縮放級別。但是，如果提供了 markers 參數(shù)，您也可以改用靜態(tài)地圖 API 來隱式確定正確的中心和縮放級別，具體取決于對這些標(biāo)記位置的估算。如果提供兩個(gè)或兩個(gè)以上的標(biāo)記，靜態(tài)地圖 API 將確定適當(dāng)?shù)闹行暮涂s放級別，從而提供足夠的邊距以顯示 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|. 等。請注意，路徑點(diǎn)使用管道字符 (|) 相互隔開。（如果對網(wǎng)址進(jìn)行編碼，管道字符在 ASCII 中也顯示為 %7C。）路徑屬性每個(gè) path 參數(shù)的開頭都可能是指定路徑屬性的可選字符串，由“pathColorType”和該類型的值組成（使用冒號分隔）。如果需要默認(rèn)的路徑屬性，可能忽略路徑描述符中的路徑屬性前綴；在本例中，路徑描述符的第一個(gè)參數(shù)描述路徑聲明中的第一個(gè)點(diǎn)。（請參見下面的路徑點(diǎn)。）有兩種可能的“pathColorType”： rgb 指定標(biāo)準(zhǔn)的 RGB 顏色方案，使用 0xffffff 形式的 24 位十六進(jìn)制值顏色