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.
The Search API supports querying in the following scripts:
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.
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:
- 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)
- House number (not parcel number)
Right now, we do not index:
- Building names
- Building sub-codes
- Named entrances or intersections
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.
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,
〒135-0063 １丁目６番７号 will both return the same result as the top-ranked item.
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
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.
- 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
横浜町横浜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,
To report issues with the limited release of the Search API in Japan during the public beta phase, contact us.