All docsHelpTroubleshootingJapan-specific considerations for the Search API

Japan-specific considerations for the Search API

Public beta for the Search API

The Mapbox Search API is in public beta. During the public beta period, the Mapbox Search API is only available for Japanese-language queries for locations in Japan. If you want a service that provides worldwide search results for queries in a variety of languages, use the Mapbox Geocoding API.

Your feedback will help us improve the Search API during the public beta phase.

When you are using the Mapbox Search API to do Japanese-language searches for Japanese locations, several factors can impact the quality of the results you receive. These factors include the scripts that the Search API supports, the Japanese address data coverage, how to format search queries, and known issues with using the Search API.

Supported scripts

The Search API supports querying in the following scripts:

  • Kanji
  • Hiragana
  • Katakana
  • Romaji

Different scripts can be mixed in the same query. The phonetic scripts are more ambiguous than Kanji, so they typically require more address information to be able to return an unambiguous correct result.

Numeric portions of the address can be entered with Kanji or Arabic numerals, and chome, block, and house can be indicated with Kanji or hyphen separators.

Japanese address data coverage

The Search API exposes the Zenrin address database, which has quality coverage of the whole country of Japan. Each address in the database contains the following information:

  • Postcode
  • Prefecture
  • Municipality (may include a combination of the city, ward, town, or district)
  • Oaza (including one intersecting street name for Kyoto)
  • Chome (but named aza are typically not supported)
  • Block
  • House number (not parcel number)

Right now, we do not index:

  • Building names
  • Floors
  • Building sub-codes
  • Named entrances or intersections

Formatting Japanese addresses

Keep the following in mind for formatting addresses in Search API queries:

  • When possible, omit extraneous information like building names, floor names, and 入口 (entrance) indicators in user queries. The Search API is able to ignore some extraneous information, but generally returns more accurate results when this information is omitted.
  • Writing parts of the address out of canonical order (for example, 有明有明東京都江東区) is supported, although in some cases it may degrade search quality.
  • The Search API supports 番地 (block) as well as 番号 (building number) addresses.

Full or partial addresses

Search API queries with a fully-specified canonical address should have high success rates. For example: 東京都江東区有明1−6−7.

Often, a subset of the information is enough to unambiguously identify a result. For instance, 有明1−6−7 and 〒135-0063 1丁目6番7号 will both return the same result as the top-ranked item.

Administrative units

The Search API supports searching for any administrative unit, but searching for municipalities or oazas on their own can be relatively ambiguous.

The Search API will try to return the highest-precision administrative unit that is a good match for the query. For example, a query for 有明有明1丁目 should rank 東京都江東区有明1丁目 above 東京都江東区有明1丁目 6番.

Kyoto-style addresses

If street names are provided in Kyoto-style addresses, the Search API uses them to disambiguate which part of an oaza the address matches. The Search API does not support addressing based solely on street name intersections.

Known issues for Japanese address searches

  • Duplicate names in a query: The Search API is not good at distinguishing the difference between a term appearing once or twice in a query. For example, the search phrase 横浜 will return 横浜町横浜 in Aomori prefecture, because matching on town and oaza appears better than only matching on city for Kanagawa’s Yokohama.
  • Atypical addresses: Out of the millions of addresses in our dataset, there are a few hundred thousand that break our expectations in some way. For example, the oaza 浜7番町 is incorrectly interpreted as referring to a block 7. Although Mapbox has programmatically identified a few hundred thousand atypical addresses, in most cases the Search API is still able to return correct results because there is redundant information in the query. We are focused on identifying as many of these cases as possible and improving our results.
  • Synonyms: The Search API has limited support for handling common variants of place names (for example, ヶ丘 vs. が丘).

To report issues with the limited release of the Search API in Japan during the public beta phase, contact us.