Geocoding V6

Mapbox Geocoding APIにはフォワードジオコーディングとリバースジオコーディングがあります。

フォワードジオコーディングでは2 Lincoln Memorial Circle SWを-77.050,38.889というように位置情報を地理座標に変換します。

リバースジオコーディングでは-77.050,38.889を2 Lincoln Memorial Circle SWというように地理座標を位置情報に変換します。この地名は、個々の住所から、与えられた座標を含む州や国まで、さまざまな種類の名前があります。

{
  ja-Kana:"ヤマグチケンシモノセキシシンアカダニシマチ"
  ja-Latn:"yamaguchiken shimonosekishi shinakadanishimachi"
}

Mapbox Geocoding APIの背景情報とその仕組みについては、How geocoding works guideをご参照ください。

また、Mapbox Geocoding APIを直接使用するのではなく、ラッパーライブラリを使用してアプリケーションに統合することもできます。

エンドポイント

The Geocoding API includes three different endpoints: /forward, /reverse, and /batch.

フォワード

リバース

バッチ

Geographic Feature Types（地理的特徴タイプ）

Mapbox geocoder では、さまざまなタイプの地理的特徴を利用できます。どのタイプも、トップレベルのレスポンスのコンテキストとして、またはtypesパラメータを使用したフィルタリングオプションとして表示されるかもしれません。また、すべての特徴が世界のすべての地域で利用可能または関連するわけではありません。世界の行政階層を正しく把握するために、必要に応じて新しいタイプが追加されることがあります。

地理的特徴の種類は、大きいものから順に列挙されています。

データの保存

MapboxのGeocoding APIは、パーマネントとテンポラリの2種類の結果保存を提供します。

テンポラリ結果はキャッシュさ れませんが、パーマネント結果はキャッシュされ、無期限で保存されます。

Geocoding APIでパーマネントストレージを使用するには、有効なクレジットカードが登録されているか、エンタープライズ契約が必要です。

デフォルトでは、ジオコーダーはテンポラリジオコーディングを使用します。パーマネントジオコーディングを使用するには、オプションのpermanentパラメータをtrueに設定します。

フォワードジオコーディング

フォワードジオコーディングクエリタイプでは、名前で場所を調べ、その標準的な住所、地理的なコンテキスト、座標を返すことができます。

以下のオプションのパラメータを使用すると、フォワードジオコーディングクエリの結果をさらに絞り込むことができます。

リクエスト例 : フォワードジオコーディング

# A basic forward geocoding request
# Find Los Angeles

$ curl "https://api.mapbox.com/search/geocode/v6/forward?q=Los%20Angeles&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Find a town called 'Chester' in a specific region
# Add the proximity parameter with local coordinates
# This ensures the town of Chester, New Jersey is in the results

$ curl "https://api.mapbox.com/search/geocode/v6/forward?q=chester&proximity=-74.70850,40.78375&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Specify types=country to search only for countries named Georgia
# Results will exclude the American state of Georgia

$ curl "https://api.mapbox.com/search/geocode/v6/forward?q=georgia&types=country&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Limit the results to two results using the limit option
# Even though there are many possible matches
# for "Washington", this query will only return two results.

$ curl "https://api.mapbox.com/search/geocode/v6/forward?q=Washington&limit=2&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Search for the Place feature "Kaaleng" in the Ilemi Triangle. Specifying the cn worldview will return the country value South Sudan. Not including leaving the worldview parameter would default to the us worldview and return the country value Kenya.

$ curl "https://api.mapbox.com/search/geocode/v6/forward?q=Kaaleng&worldview=cn&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

レスポンス：フォワードジオコーディング

Geocoding API レスポンスオブジェクトを参照。

Structured Input(構造化されたインプット)

Structured Inputは、Forward geocoding検索の一種で、検索クエリの各要素の特徴タイプをタイプ別に定義することができます。これにより、きちんとした形式のデータセットに対する結果の精度を高めることができます。Structured Inputを使用するには、qパラメータを削除して、個々のフィーチャコンポーネント用の個別のパラメータを使用する必要があります。

Structured Inputのリクエストは、次のようなクエリに置き換えて行うことができます。
q=1600%20Pennsylvania%20Avenue%20Washington,%20D.C.%2020500
と
address_number=1600&street=Pennsylvania%20Avenue&place=Washington,%20D.C.&postcode=20500

最適な結果を得るには、クエリの各要素にフィーチャタイプを割り当て、オートコンプリートをfalseに設定する必要があります。

Structured Inputクエリでは、以下のフィーチャータイプを定義することができます。

リクエスト例 : Structured Input

$ curl --location --request GET "https://api.mapbox.com/search/geocode/v6/forward?access_token=YOUR_MAPBOX_ACCESS_TOKEN&country=us&address_number=1600&street=pennsylvania%20ave%20nw&postcode=20500&place=Washington%20dc"

リバースジオコーディング

リバースジオコーディングのクエリタイプでは、一対の座標を検索し、標準的な住所や場所、および全地域のコンテキストを含む、そこの地理的特徴を返すことができます。

リバースジオコーディングクエリの結果は、以下のオプションパラメータでさらに絞り込むことができます。

リクエスト例：リバースジオコーディング

# A basic reverse geocoding request
# Retrieve places near a specific location

$ curl "https://api.mapbox.com/search/geocode/v6/reverse?longitude=-73.989&latitude=40.733&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Filter results to only include addresses

$ curl "https://api.mapbox.com/search/geocode/v6/reverse?longitude=-73.989&latitude=40.733&types=address&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Query within the Ilemi Triangle to return features for the us worldview

$ curl "https://api.mapbox.com/search/geocode/v6/reverse?longitude=35.4628&latitude=4.8975&worldview=us&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

レスポンス：リバースジオコーディング

リバースジオコーディングクエリの APIレスポンスは、Mapbox Geocoding ResponseフォーマットのGeoJSON機能コレクションを返します。Geocoding API からの応答がどのようにフォーマットされるかの詳細については、Geocoding APIレスポンスオブジェクトを参照してください。

バッチジオコーディング

バッチジオコーディングクエリタイプでは、1回のリクエストで最大1000件のフォワードまたはリバースジオコーディングクエリをリクエストすることができます

バッチジオコーディングリクエストは、リクエストのBODYとして渡されるJSONオブジェクトとしてフォーマットされますが、複数の検索クエリが次々に表示されます。URL文字列でクエリパラメーターとして定義されていたフィールドは、JSONオブジェクトのフィールドとなります。

1つのバッチジオコーディングリクエストで、フォワードクエリ、フォワード構造入力クエリ、リバースクエリなど、さまざまなタイプのクエリをバンドルすることができます。例えば、あるクエリではIPプロキシミティがオンに設定され、他のクエリではオフに設定されるなど、各クエリに個別にパラメータを設定することも可能です。

ジオコーディングの一括リクエストは、以下のボディを持つHTTP POSTリクエストで行うことができます。

https://api.mapbox.com/search/geocode/v6/batch

リクエストボディ

[
    {
        "types": ["address"],
        "q": "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States",
        "bbox": [-80, 35, -70, 40],
        "limit": 1
    },
    {
        "types": ["address"],
        "longitude": -73.986136,
        "latitude": 40.748895
    }
]

リクエスト例：バッチジオコーディング

$ curl --location --request POST "https://api.mapbox.com/search/geocode/v6/batch?access_token=YOUR_MAPBOX_ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '[
    {/**** FORWARD GEOCODING REQUEST ****/
        "types": ["address"],
        "q": "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States",
        "bbox": [-80, 35, -70, 40],
        "limit": 1
    },
    { /**** FORWARD GEOCODING REQUEST USING STRUCTURED INPUT ****/
        "country": "us",
        "address_number": "1600",
        "street": "Pennsylvania Avenue NW",
        "postcode": "20500",
        "place": "Washington, DC"
    },
    {/**** REVERSE GEOCODING REQUEST ****/
        "types": ["address"],
        "longitude": -73.986136,
        "latitude": 40.748895
    }
]'

レスポンス：バッチジオコーディング

バッチジオコーディングクエリのレスポンスは、バッチプロパティを持つオブジェクトです。バッチプロパティはGeoJSONフィーチャコレクション形式の結果の配列です。リクエスト内のクエリの順序は、バッチ配列内の対応するオブジェクトの順序を決定します。バッチ内の特定のクエリに対して結果が返されない場合、そのクエリの特徴配列は空になります( "features": [] )

ここでは、3つのクエリのリストがあるリクエストの例を示します。最初の2つのリクエストはフォワードジオコーディングで、最後の1つはリバースジオコーディングです。

$ curl --location --request POST 'https://api.mapbox.com/search/geocode/v6/batch?access_token=YOUR_MAPBOX_ACCESS_TOKEN&permanent=true' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "types": ["address"],
        "q": "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States",
        "bbox": [-80, 35, -70, 40],
        "limit": 1
    },
    {
        "types": ["address"],
        "q": "aslkdjf",
        "bbox": [-80, 35, -70, 40]
    },
    {
        "types": ["address"],
        "longitude": -73.986136,
        "latitude": 40.748895
    }
]'

レスポンスでは、結果はリクエストのクエリと同じ順番になっていることに注意してください。2番目のクエリaslkdjfは結果を返しませんが、配列の2番目の位置にまだ存在しています。

{
  "batch": [
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Point",
            "coordinates": [-77.03655, 38.89768]
          },
          "properties": {
            "mapbox_id": "address.79487136243238",
            "feature_type": "address",
            "name": "1600 Pennsylvania Avenue Northwest",
            "coordinates": {
              "longitude": -77.03655,
              "latitude": 38.89768,
              "accuracy": "rooftop"
            },
            "place_formatted": "Washington, District of Columbia 20500, United States",
            "street": "Pennsylvania Avenue Northwest",
            "address_number": "1600",
            "match_code": {
              "confidence": "exact"
            },
            "context": {
              "neighborhood": {
                "id": "neighborhood.429993196",
                "name": "National Mall"
              },
              "postcode": {
                "id": "postcode.63000300",
                "name": "20500"
              },
              "place": {
                "id": "place.345549036",
                "name": "Washington",
                "wikidata_id": "Q61"
              },
              "region": {
                "id": "region.328940",
                "name": "District of Columbia",
                "wikidata_id": "Q3551781",
                "region_code": "DC",
                "region_code_full": "US-DC"
              },
              "country": {
                "id": "country.8940",
                "name": "United States",
                "wikidata_id": "Q30",
                "country_code": "US",
                "country_code_alpha_3": "USA"
              }
            }
          }
        }
      ],
      "attribution": "NOTICE: © 2022 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service (https://www.mapbox.com/about/maps/). This response and the information it contains may not be retained."
    },
    {
      "type": "FeatureCollection",
      "features": [],
      "attribution": "NOTICE: © 2022 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service (https://www.mapbox.com/about/maps/). This response and the information it contains may not be retained."
    },
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Point",
            "coordinates": [ -73.9861365, 40.7488949]
          },
          "properties": {
            "mapbox_id": "address.3300040920421386",
            "feature_type": "address",
            "name": "20 West 34th Street",
            "coordinates": {
              "longitude": -73.9861365,
              "latitude": 40.7488949,
              "accuracy": "rooftop"
            },
            "place_formatted": "New York, New York 10118, United States",
            "street": "West 34th Street",
            "address_number": "20",
            "context": {
              "neighborhood": {
                "id": "neighborhood.338136300",
                "name": "Koreatown"
              },
              "postcode": {
                "id": "postcode.25169644",
                "name": "10118"
              },
              "locality": {
                "id": "locality.338856684",
                "name": "Manhattan",
                "wikidata_id": "Q11299"
              },
              "place": {
                "id": "place.233720044",
                "name": "New York",
                "wikidata_id": "Q60"
              },
              "district": {
                "id": "district.17000172",
                "name": "New York County",
                "wikidata_id": "Q500416"
              },
              "region": {
                "id": "region.107756",
                "name": "New York",
                "wikidata_id": "Q1384",
                "region_code": "NY",
                "region_code_full": "US-NY"
              },
              "country": {
                "id": "country.8940",
                "name": "United States",
                "wikidata_id": "Q30",
                "country_code": "US",
                "country_code_alpha_3": "USA"
              }
            }
          }
        }
      ],
      "attribution": "NOTICE: © 2022 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service (https://www.mapbox.com/about/maps/). This response and the information it contains may not be retained."
    }
  ]
}

ジオコーディングレスポンスオブジェクト

Geocoding APIリクエストのレスポンスは、以下のプロパティを含むオブジェクトとなります。

Mapboxのジオコーディングデータは常に更新・改善されています。このため、レスポンスオブジェクトのプロパティの値は保証されず、API の同一バージョン内で変更される可能性があります。プロパティは、同じ API バージョン内でレスポンスに追加されることはあっても、削除されることはありません。

フィーチャ配列に含まれる各フィーチャオブジェクトは、以下のような特性を持ちます。

フィーチャ内の各プロパティオブジェクトは、以下のような属性を持ちます。

コンテキストオブジェクト

propertiesの中のcontextオブジェクトは、与えられた住所や場所の地理的な階層を完全に分割する強力なデータの一部である。 これは、住所の各構成要素の名前付き値にアクセスする信頼性の高い方法であり、さらにWikidata idや3文字のアルファ国コードなどの特徴的なデータも含んでいます。

コンテキストの各要素には、常にidとnameが関連付けられています。 idは、フォワードジオコーディング検索で直接取得し、別の地理層に移動させることができます。

コンテキストオブジェクトの例

以下は、アドレス「2595 Lucky John Drive, Park City, Utah 84060, United States」に対して返されるコンテキストオブジェクトの例です。

"context": {
  "address": {
    "id": "address.6138109690120274",
    "street_name": "Lucky John Drive",
    "address_number": "2595",
    "name": "2595 Lucky John Drive"
  },
  "street": {
    "id": "street.6138109690120274",
    "name": "Lucky John Drive"
  },
  "neighborhood": {
    "id": "neighborhood.483568876",
    "name": "Park Meadows"
  },
  "postcode": {
    "id": "postcode.287166188",
    "name": "84060"
  },
  "place": {
    "id": "place.251619564",
    "name": "Park City",
    "wikidata_id": "Q482993"
  },
  "district": {
    "id": "district.22333164",
    "name": "Summit County",
    "wikidata_id": "Q484563"
  },
  "region": {
    "id": "region.410860",
    "name": "Utah",
    "wikidata_id": "Q829",
    "region_code": "UT",
    "region_code_full": "US-UT"
  },
  "country": {
    "id": "country.8940",
    "name": "United States",
    "wikidata_id": "Q30",
    "country_code": "US",
    "country_code_alpha_3": "USA"
  }
}

マッチコード

マッチコードはaddressフィーチャのジオコーディングレスポンスオブジェクトの一部である。 マッチコードは、結果がクエリ文字列とどの程度一致するかを、各住所の構成要素ごとに示し、 各アドレスフィーチャは matched、unmatchedとしてスコアリングされ、総合的な confidence スコアが与えられ、結果がトータルでどの程度クエリ文字列と一致したかを示します。

addressフィーチャのポイント精度

Geocoding APIレスポンスオブジェクトの coordinates.accuracy プロパティは、返された address フィーチャのポイント精度メトリックです。このリストは変更される可能性があります。

スマートアドレスマッチ

Geocoding APIのmatch_codeオブジェクトは、結果の住所フィーチャが送信されたクエリとどのように一致しているかを理解するのに最適です。 住所タイプのフィーチャに対してのみ利用可能な match_code は、結果の各要素がクエリとどのようにマッチするかの内訳と、マッチ度合いに基づく全体的な Confidence スコアを提供します。 これは、クエリのファジーマッチングに対するアプリケーションの許容範囲に基づいて、どの結果を残すか、または放棄するかを決定するのに役立ちます。

スマートアドレスマッチは、addressタイプのフィーチャを返すすべてのフォワードジオコーディングリクエストで利用できます。 リクエストのコンポーネントを明確にタイプする必要があるため、Structured Input forward queryを使用する場合に効果的です。

マッチコード例

リクエスト

/forward?&address_number=2595&street=lucky john dr&place=park city&region=CO

レスポンス

name:"2595 Lucky John Drive",
place_formatted:"Park City, Utah 84060, United States",
match_code:{
  address_number:"matched",
  street:"matched",
  postcode:"unmatched",
  place:"matched",
  region:"unmatched",
  locality:"not_applicable",
  country:"inferred",
  confidence:"medium",
},

レスポンス例：　フォワードジオコーディング

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-87.92071, 42.16482] },
      "properties": {
        "mapbox_id": "address.892839926089554",
        "feature_type": "street",
        "name": "North Milwaukee Avenue",
        "coordinates": { "longitude": -87.92071, "latitude": 42.16482 },
        "place_formatted": "Deerfield, Illinois 60015, United States",
        "context": {
          "neighborhood": {
            "id": "neighborhood.341437676",
            "name": "Lake Cook Road"
          },
          "postcode": { "id": "postcode.205377260", "name": "60015" },
          "place": {
            "id": "place.82544876",
            "name": "Deerfield",
            "wikidata_id": "Q287895"
          },
          "district": {
            "id": "district.12805868",
            "name": "Lake County",
            "wikidata_id": "Q484263"
          },
          "region": {
            "id": "region.17644",
            "name": "Illinois",
            "wikidata_id": "Q1204",
            "region_code": "IL",
            "region_code_full": "US-IL"
          },
          "country": {
            "id": "country.8940",
            "name": "United States",
            "wikidata_id": "Q30",
            "country_code": "US",
            "country_code_alpha_3": "USA"
          }
        }
      }
    },
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-87.899243, 42.12776] },
      "properties": {
        "mapbox_id": "address.1551691074851980",
        "feature_type": "address",
        "name": "825 South Milwaukee Avenue",
        "coordinates": {
          "longitude": -87.899243,
          "latitude": 42.12776,
          "accuracy": "interpolated"
        },
        "place_formatted": "Wheeling, Illinois 60090, United States",
        "street": "South Milwaukee Avenue",
        "address_number": "825",
        "match_code": { "confidence": "medium" },
        "context": {
          "neighborhood": {
            "id": "neighborhood.409963756",
            "name": "Milwaukee Avenue"
          },
          "postcode": { "id": "postcode.205868780", "name": "60090" },
          "place": {
            "id": "place.355723500",
            "name": "Wheeling",
            "wikidata_id": "Q935043"
          },
          "district": {
            "id": "district.5162732",
            "name": "Cook County",
            "wikidata_id": "Q108418"
          },
          "region": {
            "id": "region.17644",
            "name": "Illinois",
            "wikidata_id": "Q1204",
            "region_code": "IL",
            "region_code_full": "US-IL"
          },
          "country": {
            "id": "country.8940",
            "name": "United States",
            "wikidata_id": "Q30",
            "country_code": "US",
            "country_code_alpha_3": "USA"
          }
        }
      }
    },
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-87.939829, 42.224036] },
      "properties": {
        "mapbox_id": "address.1977292014921416",
        "feature_type": "address",
        "name": "825 Milwaukee Avenue",
        "coordinates": {
          "longitude": -87.939829,
          "latitude": 42.224036,
          "accuracy": "interpolated"
        },
        "place_formatted": "Vernon Hills, Illinois 60061, United States",
        "street": "Milwaukee Avenue",
        "address_number": "825",
        "match_code": { "confidence": "medium" },
        "context": {
          "neighborhood": {
            "id": "neighborhood.604703980",
            "name": "South Vernon Hills"
          },
          "postcode": { "id": "postcode.205655788", "name": "60061" },
          "place": {
            "id": "place.338757868",
            "name": "Vernon Hills",
            "wikidata_id": "Q1973428"
          },
          "district": {
            "id": "district.12805868",
            "name": "Lake County",
            "wikidata_id": "Q484263"
          },
          "region": {
            "id": "region.17644",
            "name": "Illinois",
            "wikidata_id": "Q1204",
            "region_code": "IL",
            "region_code_full": "US-IL"
          },
          "country": {
            "id": "country.8940",
            "name": "United States",
            "wikidata_id": "Q30",
            "country_code": "US",
            "country_code_alpha_3": "USA"
          }
        }
      }
    },
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-87.8921, 42.10698] },
      "properties": {
        "mapbox_id": "address.6946142334774792",
        "feature_type": "street",
        "name": "South Milwaukee Avenue",
        "coordinates": { "longitude": -87.8921, "latitude": 42.10698 },
        "place_formatted": "Prospect Heights, Illinois 60070, United States",
        "context": {
          "neighborhood": {
            "id": "neighborhood.730049772",
            "name": "Wolf Ridge"
          },
          "postcode": { "id": "postcode.205713132", "name": "60070" },
          "place": {
            "id": "place.268830956",
            "name": "Prospect Heights",
            "wikidata_id": "Q576257"
          },
          "district": {
            "id": "district.5162732",
            "name": "Cook County",
            "wikidata_id": "Q108418"
          },
          "region": {
            "id": "region.17644",
            "name": "Illinois",
            "wikidata_id": "Q1204",
            "region_code": "IL",
            "region_code_full": "US-IL"
          },
          "country": {
            "id": "country.8940",
            "name": "United States",
            "wikidata_id": "Q30",
            "country_code": "US",
            "country_code_alpha_3": "USA"
          }
        }
      }
    },
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-87.90284, 42.11827] },
      "properties": {
        "mapbox_id": "address.5576157398106678",
        "feature_type": "street",
        "name": "S Milwaukee Ave",
        "coordinates": { "longitude": -87.90284, "latitude": 42.11827 },
        "place_formatted": "Wheeling, Illinois 60090, United States",
        "context": {
          "neighborhood": {
            "id": "neighborhood.730049772",
            "name": "Wolf Ridge"
          },
          "postcode": { "id": "postcode.205868780", "name": "60090" },
          "place": {
            "id": "place.355723500",
            "name": "Wheeling",
            "wikidata_id": "Q935043"
          },
          "district": {
            "id": "district.5162732",
            "name": "Cook County",
            "wikidata_id": "Q108418"
          },
          "region": {
            "id": "region.17644",
            "name": "Illinois",
            "wikidata_id": "Q1204",
            "region_code": "IL",
            "region_code_full": "US-IL"
          },
          "country": {
            "id": "country.8940",
            "name": "United States",
            "wikidata_id": "Q30",
            "country_code": "US",
            "country_code_alpha_3": "USA"
          }
        }
      }
    }
  ],
  "attribution": "NOTICE: © 2022 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service (https://www.mapbox.com/about/maps/). This response and the information it contains may not be retained."
}

Worldviews

オプションのworldviewパラメータを使用すると、さまざまな地域、文化、または政治グループに属するオーディエンスによって、その特性が異なるように定義される地理的特徴を特定することができます。Geocoding APIは、国および地域データ型のworldviewのみをサポートしていますが、将来的には他のデータ型にも拡張される可能性があります。

利用可能なworldview

Geocoding API は、worldviewパラメータとして、以下の値をサポートしています。

返されたフィーチャは、上記の国それぞれの政府によって正式に使用が認められていないものです。

各クエリは最大1つの worldviewをサポートします。1 回の検索で複数の worldview をクエリしようとすると、エラーメッセージが表示されます。worldview が選択されていない場合、Geocoding API は us worldview のフィーチャを返します。

worldviewパラメータを利用する

Mapboxでは、worldviewデータフィールドを使用して、さまざまな地域、文化、政治グループに属するオーディエンスによって特性が異なって定義されている地理的特徴を特定します。worldviewを設定すると、所有権や定義が一致しない地域にある住所に対して返される場所の値に影響します。

例えば、東エクアトリア（南スーダン）とトゥルカナ（ケニア）の国境にあるイレミ・トライアングルの住所を例に考えてみましょう。選択したworldviewによって、この場所の住所は異なる国の文脈で返されることになります。

• worldview=cnの場合、Kaaleng、Eastern Equatoria、South Sudanのいずれかが返されます
• worldview=usの場合、Kaaleng、Turkana、Kenyaのいずれかが返されます。

つまり、wordlview=cn worldviewとケニア（ke）国フィルタを併用すると、この地域の住所の検索はうまくいきません。代わりに、南スーダン（ss）の国別フィルターと組み合わせてworldview=cnを使用する必要があります。

worldviewとcountryパラメータを組み合わせる場合、これらの指標は緩やかに結合しているに過ぎないため、注意が必要です。

worldviewの値を変更すると、地図上に表示される境界線にどのような影響があるのかを示す視覚的な例として、コンパニオンマップの境界線サービスを参照してください。

対応言語

翻訳の可否は言語や地域によって異なります。現在は以下の言語サポートを提供しています。

グローバルカバレッジ

これらの言語は、国、地域、著名な場所のフィーチャにほぼ必ず用意されています。

ローカルカバレッジ

これらの言語は、グローバルなカバレッジには劣るかもしれませんが、country、region、そして広く使われている著名なplace機能では、ほぼ存在します。

リミテッドカバレッジ

これらの言語は使用されていますが、その範囲は一貫性がなく、地理的な制約があります。

Geocoding APIのレスポンスのフォーマットやプロパティについては、レスポンスオブジェクトをご参照ください。

Geocoding APIエラー

ジオコーディングの制約と制限

Geocoding APIを保護し、サービスの安定性を最大化するため、Geocoding APIリクエストをレート制限しています。

• デフォルトのGeocoding APIのレート制限は 1 分あたり1000リクエストですが、アカウントごとに調整することができます。Mapboxは、適切と判断した場合、高トラフィックのアプリケーションに対応するため、または不正使用を防止するために、レート制限を自動的に調整する場合があります。
• レートリミットに達した場合は、HTTPエラーコード429が返されます。
• If you require a higher rate limit, contact us.

Geocoding APIの価格

Geocoding APIの使用量は、APIリクエストで測定されます。無料版に含まれるリクエスト数、および無料版に含まれる以上のリクエストあたりのコストについての詳細は料金ページでご確認いただけます。Geocoding APIからの応答は、Mapboxマップと組み合わせてのみ使用できます。

オートコンプリートと価格

Geocoding APIのautocompleteパラメータは、デフォルトで有効になっています。オートコンプリートを有効にして API を使用する場合、キーストロークごとに1つの API リクエストが蓄積されることになります。たとえば、オートコンプリートを有効にして、ユーザーが検索バーに文字を入力するたびに Geocoding APIリクエストを作成するようにアプリケーションを設定した場合、「カリフォルニア」を探して「Cali」と入力したユーザーは、1文字につき1回、4つのGeocoding APIリクエストを作成することになります。

オートコンプリートを有効にしている間のリクエスト数を減らすために、特定の文字数が入力されるまでAPIリクエストの作成を開始するのを待つことができます。Geocoding APIにはリクエストを制限するパラメータが組み込まれていませんが、そのオプションを持つMapbox GL Geocoderを使用するか、アプリケーションに直接記述することができます。

バッチジオコーディングと価格

バッジジオコーディングでは、1つのリクエストで複数のジオコーディングクエリを行うことができます。バッチジオコーディングのリクエストに含まれる個々の検索は、1つのリクエストとしてカウントされます。例えば、3つの検索を含むリクエストは、3つのリクエストとしてカウントされ、そのように課金されます。この3つのリクエストは、統計グラフと請求書に反映されます。