Japan-specific considerations 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: 東京都江東区有明１−６−７.
Often, a subset of the information is enough to unambiguously identify a result. For instance, 有明１−６−７ and 〒135-0063 １丁目６番７号 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 有明有明１丁目 should rank 東京都江東区有明１丁目 above 東京都江東区有明１丁目 ６番.
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.