Japan

To reflect the Japanese administrative system and to support Japan use cases, we provide a response that includes block and subblock as additional hierarchical structures to support the country-specific scheme like chiban, aza, etc.

Getting Credentials

Use of Geocoding and Search Japan requires a premium credential. For more information, see Get Credentials.

Discover

For more information, see Discover.

To discover the nearest station at the geo-position (35.6899274, 139.8268034) use the following request:

GET https://discover.search.hereapi.com/v1/
    discover
    ?at=35.7007524,139.8184107
    &q=駅
    &limit=2
    &apiKey={YOUR_API_KEY}

The response to the above request is the following:

{
   items: [
      {
         title: "錦糸町駅",
         id: here:xs1:place:sta_55409928,
         ontologyId: "here:cm:ontology:railway_station",
         resultType: "place",
         address: {
            label: "東京都墨田区錦糸町駅",
            countryCode: "JPN",
            countryName: "日本",
            state: "東京都",
            city: "墨田区"
         },
         position: {
            lat: 35.69674,
            lng: 139.81424
         },
         access: [
            {
               lat: 35.69674,
               lng: 139.81424
            }
         ],
         distance: 584,
         categories: [
            {
               id: "400-4100-0035",
               name: "駅",
               primary: true
            }
         ]
      },
      {
         title: "亀戸駅",
         id: here:xs1:place:sta_55414903,
         ontologyId: "here:cm:ontology:railway_station",
         resultType: "place",
         address: {
            label: "東京都江東区亀戸駅",
            countryCode: "JPN",
            countryName: "日本",
            state: "東京都",
            city: "江東区"
         },
         position: {
            lat: 35.69771,
            lng: 139.82646
         },
         access: [
            {
               lat: 35.69771,
               lng: 139.82646
            }
         ],
         distance: 802,
         categories: [
            {
               id: "400-4100-0035",
               name: "駅",
               primary: true
            }
         ]
      }
   ]
}

Geocode

For more information, see Geocode.

A free-form text query for address in Tokyo, 港区六本木6-10-1 is the following:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=港区六本木6-10-1
    &apiKey={YOUR_API_KEY}

The response to the above request is the following:

{
   title: "〒106-0032 東京都港区六本木6丁目10-1",
   id: here:xs1:pointaddress:45184649:CgcIBCCTxvwREAEaATEoZA,
   resultType: "houseNumber",
   houseNumberType: "PA",
   address: {
      label: "〒106-0032 東京都港区六本木6丁目10-1",
      countryCode: "JPN",
      countryName: "日本",
      state: "東京都",
      city: "港区",
      subdistrict: "六本木",
      block: "6丁目",
      subblock: "10",
      postalCode: "106-0032",
      houseNumber: "1"
   },
   position: {
      lat: 35.66045,
      lng: 139.72923
   },
   access: [
      {
         lat: 35.66045,
         lng: 139.72923
      }
   ],
   mapView: {
      west: 139.72812,
      south: 35.65955,
      east: 139.73034,
      north: 35.66135
   },
   scoring: {
      queryScore: 1,
      fieldScore: {
         city: 1,
         subdistrict: 1,
         block: 1,
         subblock: 1,
         houseNumber: 1
      }
   }
}

A free-form text query for address in Kumamoto Prefecture, 熊本県菊池郡大津町引水１８-３ is the following:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=熊本県菊池郡大津町引水18-3
    &apiKey={YOUR_API_KEY}

The response to the above request is the following:

{
   items: [
      {
         title: "〒869-1234 熊本県菊池郡大津町引水18-3",
         id: here:xs1:pointaddress:30863556:CgcIBCDh_NsOEAEaATMoZA,
         resultType: "houseNumber",
         houseNumberType: "PA",
         address: {
            label: "〒869-1234 熊本県菊池郡大津町引水18-3",
            countryCode: "JPN",
            countryName: "日本",
            state: "熊本県",
            county: "菊池郡",
            city: "大津町",
            subdistrict: "引水",
            subblock: "18",
            postalCode: "869-1234",
            houseNumber: "3"
         },
         position: {
            lat: 32.87821,
            lng: 130.87493
         },
         access: [
            {
               lat: 32.87821,
               lng: 130.87493
            }
         ],
         mapView: {
            west: 130.87386,
            south: 32.87731,
            east: 130.876,
            north: 32.87911
         },
         scoring: {
            queryScore: 1,
            fieldScore: {
               state: 1,
               county: 1,
               city: 1,
               subdistrict: 1,
               subblock: 1,
               houseNumber: 1
            }
         }
      }
   ]
}

Autosuggest

For more information, see Autosuggest.

For 大学 suggestions intending to have 大学病院 somewhere in Tokyo, a query would be the following:

GET https://autosuggest.search.hereapi.com/v1/
    autosuggest
    ?at=35.6990575,139.7623009
    &q=現代美
    &limit=2
    &apiKey={YOUR_API_KEY}

And the response is the following:

{
  items: [
    {
      title: "東京都現代美術館",
      id: here:xs1:place:fac_84088,
      resultType: "place",
      address: {
        label: "東京都江東区三好4丁目1-1東京都現代美術館"
      },
      position: {
        lat: 35.67972,
        lng: 139.80805
      },
      access: [
        {
          lat: 35.67972,
          lng: 139.80805
        }
      ],
      distance: 2039,
      categories: [
        {
          id: "300-3100-0029",
          name: "美術館",
          primary: true
        }
      ],
      highlights: {
        "title": [],
        address: {
          "label": []
        }
      }
    },
    {
      title: "現代美術館北",
      id: here:xs1:place:int_3239230,
      resultType: "place",
      address: {
        label: "東京都江東区現代美術館北"
      },
      position: {
        lat: 35.68039,
        lng: 139.80931
      },
      access: [
        {
          lat: 35.68039,
          lng: 139.80931
        }
      ],
      distance: 1903,
      categories: [
        {
          id: "900-9400-0402",
          name: "Junction",
          primary: true
        }
      ],
      highlights: {
        title: [
          {
            start: 0,
            end: 3
          }
        ],
        address: {
          label: [
            {
              start: 6,
              end: 9
            }
          ]
        }
      }
    }
  ],
  "queryTerms": []
}

Browse

For more information, see Browse.

For example, a customer application wants to expose an icon representing a convenience store, and use the category id 600-6000-0061 as the value for the categories parameter of a /browse query:

GET https://browse.search.hereapi.com/v1/
    browse
    ?at=35.7064554,139.7398739
    &categories=600-6000-0061
    &limit=2
    &apiKey={YOUR_API_KEY}

{
   items: [
      {
         title: "ファミリーマート 東五軒町店",
         id: here:xs1:place:gp_70080918,
         resultType: "place",
         address: {
            label: "東京都新宿区東五軒町5-19ファミリーマート 東五軒町店",
            countryCode: "JPN",
            countryName: "日本",
            state: "東京都",
            city: "新宿区",
            subdistrict: "東五軒町",
            subblock: "5",
            houseNumber: "19"
         },
         position: {
            lat: 35.70679,
            lng: 139.73979
         },
         access: [
            {
               lat: 35.70679,
               lng: 139.73979
            }
         ],
         distance: 37,
         categories: [
            {
               id: "600-6000-0061",
               name: "コンビニ",
               primary: true
            }
         ],
         contacts: [
            {
               phone: [
                  {
                     value: "03-5206-3351"
                  }
               ]
            }
         ]
      },
      {
         title: "ローソン 新宿新小川町",
         id: here:xs1:place:gp_70080069,
         resultType: "place",
         address: {
            label: "東京都新宿区新小川町8-9ローソン 新宿新小川町",
            countryCode: "JPN",
            countryName: "日本",
            state: "東京都",
            city: "新宿区",
            subdistrict: "新小川町",
            subblock: "8",
            houseNumber: "9"
         },
         position: {
            lat: 35.7061,
            lng: 139.74071
         },
         access: [
            {
               lat: 35.7061,
               lng: 139.74071
            }
         ],
         distance: 86,
         categories: [
            {
               id: "600-6000-0061",
               name: "コンビニ",
               primary: true
            }
         ],
         contacts: [
            {
               phone: [
                  {
                     value: "03-3267-3963"
                  }
               ]
            }
         ]
      }
   ]
}

Lookup by ID

For more information, see Lookup.

The HERE ID for 札幌站(Sapporo Station) is here:xs1:place:55409089. To retrieve details for such a place, send the following request:

GET https://lookup.search.hereapi.com/v1/
    lookup
    ?id=here:xs1:place:sta_55409089
    &apiKey={YOUR_API_KEY}

The response to the above query is the following:

{
   title: "札幌駅",
   id: here:xs1:place:sta_55409089,
   resultType: "place",
   address: {
      label: "北海道札幌市北区札幌駅",
      countryCode: "JPN",
      countryName: "日本",
      state: "北海道",
      city: "札幌市",
      district: "北区"
   },
   position: {
      lat: 43.06859,
      lng: 141.35075
   },
   access: [
      {
         lat: 43.06859,
         lng: 141.35075
      }
   ],
   categories: [
      {
         id: "400-4100-0035",
         name: "駅",
         primary: true
      }
   ]
}

Reverse Geocode

For more information, see Reverse Geocode.

For example, a user selects a point on the map in Yokohama and submits the map geo-coordinates in a request to the revgeocode endpoint as in the following:

GET https://revgeocode.search.hereapi.com/v1/
    revgeocode
    ?at=35.5888649,139.5479805
    &lang=ja-JP
    &apiKey={YOUR_API_KEY}

The response for this example shows the nearest address available.

{
   title: "〒225-0002 神奈川県横浜市青葉区美しが丘3丁目56-31",
   id: here:xs1:pointaddress:44736003:CgcIESDxjuEPEAEaAjMx,  
   resultType: "houseNumber",
   houseNumberType: "PA",
   address: {
      label: "〒225-0002 神奈川県横浜市青葉区美しが丘3丁目56-31",
      countryCode: "JPN",
      countryName: "日本",
      state: "神奈川県",
      city: "横浜市",
      district: "青葉区",
      subdistrict: "美しが丘",
      block: "3丁目",
      subblock: "56",
      postalCode: "225-0002",
      houseNumber: "31"
   },
   position: {
      lat: 35.58873,
      lng: 139.54792
   },
   access: [
      {
         lat: 35.58873,
         lng: 139.54792
      }
   ],
   distance: 16
}