第9回　使ってみよう！ Bing Maps REST Services（1）

Bing Maps REST Services

前回まではBing Map App SDKについて紹介してきました。今回からはBing Maps REST Servicesを使ってみましょう。Bing Maps REST Servicesは、ちょうどこの連載が始まる時期に登場した新しいWeb APIで、このAPIを利用すると、地理情報の取得、Bing Mapsの地図を構成するタイル画像の取得、ルート探索などが可能です。

Bing Maps REST Servicesは次の3種類のAPIに分類されています。

Locations API: 住所や経緯度、クエリーから地理情報を取得できるAPIです。
Imagery API: 地図画像を取得、プッシュピンを配置した・ルート情報を表示した地図画像の取得、タイル画像のメタデータを取得できるAPIです。
Routes API: ルートの探索ができるAPIです。

これらのAPIでは、HTTPまたはHTTPSで特定のURLにアクセスし、結果をXMLまたはJSON形式で取得します。ちなみに以前からも同様の機能は、SOAPというプロトコルでBing SOAP Serviceとして提供されていました。それらのSOAP APIに加えて、RESTという今風のAPIが追加されました。

Bing Maps REST Servicesは、今のところ公式に日本語情報は提供されていませんが、日本の地理情報を扱うことは可能です。本連載では、特に日本の地理情報の利用を想定してAPIを利用・紹介します。

Location API

今回はBing Maps REST Servicesのうち、Location APIを使ってみましょう。Location APIは、住所や経緯度などの地図情報を取得するAPIです。このAPIは、リクエスト形式によって次の3種類に分類されています。

住所から情報を取得
経緯度から情報を取得
クエリーから情報を取得

住所から経緯度などの地理情報を得る技術はジオコーディング、逆に経緯度情報から住所などの情報を得るのは逆ジオコーディングと呼びます。このAPIの特徴はどちらも同じLocation APIで扱い、リクエスト形式が異なるもののレスポンス形式は同様の内容になっています。クエリー形式は、住所や東京タワーなどの地名や施設名から情報を得る形式です。

さっそくひとつの例を見てみましょう。次のようなURLにアクセスすると、以下のJSON形式の結果を得ます。

http://dev.virtualearth.net/REST/v1/Locations?countryRegion=JP&adminDistrict=東京都&locality=新宿区&addressLine=西新宿二丁目8番1号&key=BingMapsKey&c=ja-jp

※わかりやすいよう日本語はエンコード前の値を記載しています。

{
    "authenticationResultCode": "ValidCredentials", 
    "brandLogoUri": "http://dev.virtualearth.net/Branding/logo_powered_by.png", 
    "copyright": "Copyright © 2010 Microsoft and its suppliers.（省略）", 
    "resourceSets": [
        {
            "estimatedTotal": 1, 
            "resources": [
                {
                    "__type": "Location:http://schemas.microsoft.com/search/local/ws/rest/v1", 
                    "address": {
                        "addressLine": "２丁目８－１", 
                        "adminDistrict": "東京都", 
                        "countryRegion": "日本", 
                        "formattedAddress": "東京都新宿区西新宿２丁目８－１", 
                        "locality": "新宿区", 
                        "postalCode": "160-0023"
                    }, 
                    "bbox": [
                        35.686481029111, 
                        139.68893000133298, 
                        35.691888193111005, 
                        139.694337165333
                    ], 
                    "confidence": "High", 
                    "entityType": "Address", 
                    "name": "東京都新宿区西新宿２丁目８－１", 
                    "point": {
                        "coordinates": [
                            35.689184611111003, 
                            139.69163358333299
                        ], 
                        "type": "Point"
                    }
                }
            ]
        }
    ], 
    "statusCode": 200, 
    "statusDescription": "OK", 
    "traceId": "..."
}

URLに指定した値や、レスポンスの内容を見るとある程度使い方が想像できるのではないでしょうか。レスポンス形式はJavaScriptと連携しやすいJSON以外に、各種プログラミング言語でも扱いやすいXML形式が選択できます。また、レスポンス内容もある程度カスタマイズ可能です。

Bing Maps Key

APIを利用するには、Bing Maps Keyをあらかじめ取得しておく必要があります。このKey（文字列）をURLに指定して認証します。Bing Maps KeyはBing Maps Account Center（図1）で取得します。

Keyの作成は、アプリケーションの名前・URL・種類を入力します。初めて取得する場合は、その前に開発者アカウントを作成する必要があります

Bing Maps Keyは、Bing Maps REST Services以外にBing Maps Silverlight Control SDKなどのでも使います。こちらは、Bing Maps Keyの取得方法も含めて、使ってみよう！ Windows Live SDK/API 第30回で紹介しています。

住所から情報取得

それでは順にリクエスト形式別にAPIの内容をみてみましょう。まず、住所から地理情報の取得です。住所から地理情報を取得する場合、経緯度の取得が主な目的になると思います。レスポンスの内容については既に述べたように、Bing Maps REST ServicesおよびLocation APIで共通の形式になっています。その中にはもちろん経緯度も含まれています。レスポンス内容は最後にまとめて紹介します。

Structured URL

Location APIでは、Structured URLとUnstructured URLと呼ばれる2種類のURL形式が用意されています。Structured URLは、リソースとなる郵便番号や地名を「/」で区切り、URLのディレクトリ部分に指定した形式です。米国の場合、次のように記述します。

http://dev.virtualearth.net/REST/v1/Locations/US/WA/98052/Redmond/1 Microsoft Way?o=xml&key=BingMapsKey

リクエスト結果をみる

上記の場合、州名・郵便番号・街の名前・番地が指定されています。そのあとにoパラメーターで出力形式、keyパラメーターにBing Maps Keyを指定しています。住所を指定するStructured URLは、日本には対応していませんので、紹介はこのくらいにしておきましょう。次のUnstructured URLを使用すると日本を含む世界の住所から情報を取得可能です。

Unstructured URL

Unstructured URLの形式は次のようになります。

http://dev.virtualearth.net/REST/version/Locations?
  countryRegion=countryRegion&
  adminDistrict=adminDistrict&
  locality=locality&
  postalCode=postalCode&
  addressLine=addressLine&
  key=BingMapsKey

まず、この後の内容すべてにおいて共通の部分について説明します。versionはAPIのバージョン「v+バージョン番号」で指定します。現在リリースされているAPIでは「v1」です。そしてBingMapsKeyには取得したBing Maps Keyの値を指定します。上記はHTTPですが、HTTPS（https://〜）でアクセスも可能です。

続いて各パラメーターは次のとおりです。

パラメーター	説明
countryRegion	ISOの国名コードを指定します。日本はJPです。
adminDistrict	広域な行政区域を指定します。日本では都道府県名にあたります。ただし必ずしも広域な行政区域とは限りません。
locality	adminDistrict以下の街名などを指定します。日本では主に市区群になります。
postalCode	郵便番号を指定します。
addressLine	番地などを指定します。

adminDistrict・locality・addressLineに関して、日本での分類は、SDKの文書などに明記されているわけではなくAPI利用時の実際のデータから判断した目安です。これらのパラメーターはリクエスト時にすべて指定する必要はなく、ひとつまたは複数を指定すれば問題ありません。また実際に使用してみたところ、Bing Mapsのデータベースで分類されている通りにlocalityやaddressLineを指定しなくとも、結果を得ることができました。

実際の例をみていきましょう。まず住所を番地まで指定した例です。

東京都、新宿区、西新宿二丁目8番1号
http://dev.virtualearth.net/REST/v1/Locations?
  countryRegion=JP&
  adminDistrict=東京&
  locality=新宿区&
  addressLine=西新宿二丁目8番1号&
  key=BingMapsKey&
  c=ja-jp&o=xml

リクエスト結果をみる[1]

上記は日本語をそのまま記載していますが、実際にはエンコードして指定する必要があります。最後に付いているcパラメーターは、サービス地域を表すLocation API共通のcultureパラメーターで、日本を指定しています。この指定がない場合、日本語のパラメーターでは結果が得られない場合や、レスポンスの内容が英語であったり、詳細な情報にならない場合があります。この例の場合、「⁠西新宿2-8-1」の表記でも同じ結果が得られます。

次は、一部のパラメーター名を指定した例です。あいまいな指定の場合、レスポンスに複数の場所の地理情報が含まれている場合があります。

新宿区
http://dev.virtualearth.net/REST/V1/Locations?
  locality=新宿区&
  key=BingMapsKey&
  c=ja-jp&o=xml

リクエスト結果をみる

日本の郵便番号もcountryRegionとcultureパラメーターを指定すると結果が得られます。ハイフンはあってもなくても同じ結果です。

郵便番号160-0023
http://dev.virtualearth.net/REST/V1/Locations?
  countryRegion=JP&
  postalCode=160-0023&
  key=BingMapsKey&
  c=ja-jp&o=xml

リクエスト結果をみる

adminDistrictパラメーターに村名を指定した場合です。レスポンス内容を確認すると、この村名はadminDistrict・locality・addressLineのどれにも分類されていないようですが、期待した結果を得ることができました。

千早赤阪村
http://dev.virtualearth.net/REST/V1/Locations?
  countryRegion=JP&
  adminDistrict=千早赤阪村&
  key=BingMapsKey&
  c=ja-jp&o=xml

リクエスト結果をみる

最後にローマ字で指定した場合です。cultureパラメーターを指定しない場合の規定値は、英語・米国（en-US）になります。ローマ字の場合は詳細な住所を指定すると結果は該当なしとなるようです。

JP、Tokyo、Sinjuku-ku
http://dev.virtualearth.net/REST/v1/Locations?
  countryRegion=JP&
  adminDistrict=Tokyo&
  locality=sinjuku-ku&
  key=BingMapsKey&
  o=xml

リクエスト結果をみる

経緯度から情報取得

次は、経緯度から地理情報を取得する方法です。住所から取得と異なりあまりバリエーションがありません。URLの形式は次のようになります。

http://dev.virtualearth.net/REST/v1/Locations/point?
includeEntityTypes=entityTypes&
key=BingMapsKey

pointパラメーターには、緯度・経度を「35.68918461,139.69163358」のようにカンマ区切りで指定します。当然ながら指定は必須です。

includeEntityTypeパラメーターでは、取得する情報の種類を指定する場合に使用します。たとえば完全な住所や国名だけなど、または施設名などを指定できます。ただし、日本の場合、経緯度からは都道府県程度までしか取得できないようです。使用する場合は、Address, Neighborhood, PopulatedPlace, AdminDivision1, AdminDivision2, CountryRegionの値を指定可能です。カンマ区切りで複数指定もできます。その場合、複数の結果が返るのではなく指定した順に優先して結果を得られます。

例をみてみましょう。

http://dev.virtualearth.net/REST/v1/Locations/35.68918461,139.69163358?
key=BingMapsKey&c=ja-jp&o=xml

リクエスト結果をみる

東京都庁のある経緯度ですが、レスポンスの内容をみると、東京都までの情報しか得られていません。EntityTypeはAdminDivision1になっています。

クエリーから情報取得

最後は、クエリーから地理情報を得る方法です。地図検索時に入力するような住所の一部や施設名などのキーワードから情報を取得できます。URL形式は、Structured URLとUnstructured URLの両方が用意されていますが、どちらもほぼ同じです。

Structured URL
http://dev.virtualearth.net/REST/v1/Locations/query?
key=BingMapsKey

Unstructured URL
http://dev.virtualearth.net/REST/v1/Locations?
query=query&
key=BingMapsKey

queryパラメーターに住所や施設名などを指定します。queryは省略してqと指定可能です。

例をみてみましょう。次は住所を指定した場合です。

東京都新宿区西新宿二丁目8番1号
http://dev.virtualearth.net/REST/v1/Locations?
  query=東京都新宿区西新宿二丁目8番1号&
  key=BingMapsKey&
  c=ja-jp&o=xml

リクエスト結果をみる

次は、東京だけ指定した場合です。この場合、複数の候補地が得られます。

東京
http://dev.virtualearth.net/REST/v1/Locations?
  query=東京&
  key=BingMapsKey&
  c=ja-jp&o=xml

リクエスト結果をみる

東京タワーを指定した場合です。実は、クエリー形式でなくとも、住所から地理情報を取得するURL形式でも「東京タワー」で同じ結果が得られます。

東京タワー
http://dev.virtualearth.net/REST/v1/Locations?
  query=東京タワー&
  key=BingMapsKey&
  c=ja-jp&o=xml

リクエスト結果をみる

リクエスト方法

以上3種類のリクエスト方法を紹介しましたが、それぞれのURL形式は、Location APIを含めREST Servicesで、次のURL形式をベースとしています。

http://dev.virtualearth.net/REST/version/restApi/resourcePath?queryParameters&key=BingMapsKey

versionパラメーターとkeyパラメーターは既に説明しています。APIのバージョンと、Bing Maps Keyでした。restApiパラメーターは、REST APIの種類で、今回の内容ではすべてLocationが指定されていました。resourcePathとqueryParametersパラメーターは、必要に応じて指定される値です。

共通のパラメーター

queryParametersパラメーター部分に指定でき、すべてのリクエストに共通のパラメーターがあります。

既に使用していましたが、ひとつはサービス地域を示す、culture（省略名c）パラメーターです。日本の場合ja-JPと指定します。

もうひとつ使用していたパラメーターが、レスポンスの出力形式を指定する、output(省略名o)パラメーターです。出力形式に関する指定はこれ以外にも次のパラメーターが使用できます。

パラメーター（省略名）	説明
output（o）	JSON・XML形式を選択します。 json（規定値）またはxml
suppressStatus（ss）	すべてのレスポンスのHTTPステータスを200 OKで返す。 trueまたはfalse（規定値）
jsonp	JSONP利用時に呼び出す関数名を指定。例：jsonp=MyCallbackFunction
jsonso	jsonp指定時、呼び出す関数に渡される状態オブジェクト（文字列⁠）⁠。アプリケーション側でリクエストと対応するレスポンスを結びつけるために主に利用します。

レスポンス内容

レスポンスの内容をみてみましょう。Bing Maps REST Servicesでは、出力形式にJSON・XMLの違いはありますが、次の同じ内容で構成されています。

JSON形式

{
    "authenticationResultCode" : "ValidCredentials",
    "brandLogoUri" : "http://dev.virtualearth.net/Branding/logo_powered_by.png",
    "copyright" : "Copyright © 2010 Microsoft and its suppliers. （省略）",
    "resourceSets" : [
        {
            "estimatedTotal" : 1,
            "resources" : [
                （REST APIの種類によって固有の形式の値）
            ]
        }
    ],
    "statusCode" : 200,
    "statusDescription" : "OK",
    "traceId" : "..."
}

XML形式

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
                   xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">
  <Copyright>Copyright © 2010 Microsoft and its suppliers. （省略）</Copyright>
  <BrandLogoUri>http://dev.virtualearth.net/Branding/logo_powered_by.png </BrandLogoUri>
  <StatusCode>200</StatusCode>
  <StatusDescription>OK</StatusDescription>
  <AuthenticationResultCode>ValidCredentials</AuthenticationResultCode>
  <TraceId>...</TraceId>
  <ResourceSets>
    <ResourceSet>
      <EstimatedTotal>1</EstimatedTotal>
      <Resources>
        （REST API の種類によって固有の形式の値）
      </Resources>
    </ResourceSet>
  </ResourceSets>
</Response>

それぞれの要素の内容は次の通りです。JSONとXMLで名前の大文字・小文字が異なりますが適宜読み替えてください。

要素名	説明
StatusCode	HTTPのステータスコード
StatusDescription	HTTPのステータスコードの説明
AuthenticationResultCode	認証結果のコードの説明です。以下の値のいずれかです。 ValidCredentials InvalidCredentials CredentialsExpired NotAuthorized NoCredentials None
TraceId	リクエストごとに一意な値
Copyright	コピーライト情報
BrandLogoUri	Bingロゴ画像のURL。詳しくは利用規約を参照。
ResourceSets	ResourceSetのコレクション
ErrorDetails	エラー内容のコレクション。結果がエラーの場合に含まれています。

ResourceSetsはResourceSetのコレクションです。ResourceSetに含まれる内容は次の通りです。

要素名	説明
esitmatedTotal	ResruoceSetに含まれるResrouces内の項目数の概算値
Resources	API固有の情報のコレクション

このResources要素以下の内容が、Location APIなどREST APIの内容によって異なる構成になっています。Location APIの場合Location要素がひとつ以上含まれています。Resources以下に含まれている項目（ここではLocation要素）の総数は、概算値となっているので注意してください。これは検索結果のように大量の場合も想定されていると思われます。

Location API固有の内容

Resources要素の中のLocation要素は、Location APIで使用する地理情報です。その内容はリクエスト形式によっては変わりません。

JSON・XML形式は次のようになっています。

JSON形式

{
    "__type": "Location:http://schemas.microsoft.com/search/local/ws/rest/v1", 
    "address": {
        "addressLine": "２丁目８－１", 
        "adminDistrict": "東京都", 
        "countryRegion": "日本", 
        "formattedAddress": "東京都新宿区西新宿２丁目８－１", 
        "locality": "新宿区", 
        "postalCode": "160-0023"
    }, 
    "bbox": [
        35.686481029111, 
        139.68893000133298, 
        35.691888193111005, 
        139.694337165333
    ], 
    "confidence": "High", 
    "entityType": "Address", 
    "name": "東京都新宿区西新宿２丁目８－１", 
    "point": {
        "coordinates": [
            35.689184611111003, 
            139.69163358333299
        ], 
        "type": "Point"
    }
}

XML形式

<Location>
  <Name>東京都新宿区西新宿２丁目８－１</Name>
  <Point>
    <Latitude>35.689184611111</Latitude>
    <Longitude>139.691633583333</Longitude>
  </Point>
  <BoundingBox>
    <SouthLatitude>35.686481029111</SouthLatitude>
    <WestLongitude>139.68893000133298</WestLongitude>
    <NorthLatitude>35.691888193111005</NorthLatitude>
    <EastLongitude>139.694337165333</EastLongitude>
  </BoundingBox>
  <EntityType>Address</EntityType>
  <Address>
    <AddressLine>２丁目８－１</AddressLine>
    <AdminDistrict>東京都</AdminDistrict>
    <CountryRegion>日本</CountryRegion>
    <FormattedAddress>東京都新宿区西新宿２丁目８－１</FormattedAddress>
    <Locality>新宿区</Locality>
    <PostalCode>160-0023</PostalCode>
  </Address>
  <Confidence>High</Confidence>
</Location>

Location要素の内容は次の通りです。

要素名	説明
Name	リソース名
Point	経緯度
BoundingBox	エリアを示す2点の経緯度
EntityType	リソースの種類（完全な住所や行政区域、施設名など）
Address	住所子要素に以下の項目があります。 AddressLine AdminDistrict AdminDistrict2 CountryRegion FormattedAddress Locality PostalCode
Confidence	リクエストに対する一致度を以下のいずれかで粟原しています。 High、Medium、Low、Unknown

Address要素は、リクエストの内容に対して正規化された住所となっていますので、番地を「2-8-1」と指定していても「２丁目８−１」といった値に変化しています。また、各子要素に対する情報がない場合、その子要素は省略されています。住所や地名を利用したい場合、Name要素やFormattedAddress要素（含まれている場合）を使用するとよさそうです。

EntityType要素は、記事では紹介しきれないほどの分類があります（AdminDivision1などだけではなく、AirportやZooなどもあります⁠）⁠。ただし日本の地理情報がどれだけ分類されているのかは不明です。詳しくは、SDKの文書に記載されています。MSDN LibraryからCHMまたはPDFファイルがダウンロードできます。

今回はここまでです。次回もBing Maps REST Servicesを紹介の続きです。