HeartRails Geo API

https://geoapi.heartrails.com/api.html
Admin
Japanese geographical and address information API providing prefecture, city, town, postal code, and...
Tokens:4,764
Snippets:29
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### XML Request for Keyword Search

Source: https://geoapi.heartrails.com/api.html

Example of an XML request to search for address information based on a keyword. The keyword must be URL-encoded, and a matching type (prefix, like, suffix) must be specified.

```URL
https://geoapi.heartrails.com/api/xml?method=suggest&matching=like&keyword=%E6%96%B0%E5%AE%BF%E5%8C%BA
```

--------------------------------

### Get Cities

Source: https://geoapi.heartrails.com/api.html

Retrieves a list of cities within a specified area or prefecture. This API helps in finding specific municipalities.

```APIDOC
## GET /api/xml?method=getCities

### Description
Retrieves a list of cities within a specified area or prefecture. This API helps in finding specific municipalities.

### Method
GET

### Endpoint
https://geoapi.heartrails.com/api/xml?method=getCities

### Parameters
#### Query Parameters
- **method** (string) - Required - The method name, fixed as "getCities".
- **area** (string) - Required - The URL-encoded name of the area. Either 'area' or 'prefecture' is required.
- **prefecture** (string) - Required - The URL-encoded name of the prefecture. Either 'area' or 'prefecture' is required.
- **jsonp** (string) - Optional - Callback function name for JSONP requests.

### Response
#### Success Response
- **response** (object) - Contains the list of cities.
  - **city** (string) - The name of a city.
  - **city-kana** (string) - The reading (hiragana) of the city name.
```

--------------------------------

### XML Request for Postal Code Search

Source: https://geoapi.heartrails.com/api.html

Example of an XML request to search for address information using a postal code. The postal code must be URL-encoded.

```URL
https://geoapi.heartrails.com/api/xml?method=searchByPostal&postal=0010010
```

--------------------------------

### Get Prefectures

Source: https://geoapi.heartrails.com/api.html

Retrieves a list of prefectures within a specified area. This is useful for narrowing down geographical searches.

```APIDOC
## GET /api/xml?method=getPrefectures

### Description
Retrieves a list of prefectures within a specified area. This is useful for narrowing down geographical searches.

### Method
GET

### Endpoint
https://geoapi.heartrails.com/api/xml?method=getPrefectures

### Parameters
#### Query Parameters
- **method** (string) - Required - The method name, fixed as "getPrefectures".
- **area** (string) - Optional - The URL-encoded name of the area.
- **jsonp** (string) - Optional - Callback function name for JSONP requests.

### Response
#### Success Response
- **response** (object) - Contains the list of prefectures.
  - **prefecture** (string) - The name of a prefecture.
```

--------------------------------

### Get Areas

Source: https://geoapi.heartrails.com/api.html

Retrieves a list of all available areas. This API is useful for understanding the geographical scope of the data.

```APIDOC
## GET /api/xml?method=getAreas

### Description
Retrieves a list of all available areas. This API is useful for understanding the geographical scope of the data.

### Method
GET

### Endpoint
https://geoapi.heartrails.com/api/xml?method=getAreas

### Parameters
#### Query Parameters
- **method** (string) - Required - The method name, fixed as "getAreas".
- **jsonp** (string) - Optional - Callback function name for JSONP requests.

### Response
#### Success Response
- **response** (object) - Contains the list of areas.
  - **area** (string) - The name of an area.
```

--------------------------------

### XML Request for Geolocation Search

Source: https://geoapi.heartrails.com/api.html

Example of an XML request to find address information near a specific longitude and latitude. Coordinates must be in the World Geodetic System.

```URL
https://geoapi.heartrails.com/api/xml?method=searchByGeoLocation&x=135.0&y=35.0
```

--------------------------------

### Get Towns

Source: https://geoapi.heartrails.com/api.html

Retrieves a list of towns within a specified prefecture or city, including their coordinates and postal codes. This API provides detailed address information.

```APIDOC
## GET /api/xml?method=getTowns

### Description
Retrieves a list of towns within a specified prefecture or city, including their coordinates and postal codes. This API provides detailed address information.

### Method
GET

### Endpoint
https://geoapi.heartrails.com/api/xml?method=getTowns

### Parameters
#### Query Parameters
- **method** (string) - Required - The method name, fixed as "getTowns".
- **prefecture** (string) - Required - The URL-encoded name of the prefecture. Either 'prefecture' or 'city' is required.
- **city** (string) - Required - The URL-encoded name of the city. Either 'prefecture' or 'city' is required.
- **jsonp** (string) - Optional - Callback function name for JSONP requests.

### Response
#### Success Response
- **response** (object) - Contains the list of towns.
  - **prefecture** (string) - The prefecture name for the town.
  - **city** (string) - The city name for the town.
  - **city-kana** (string) - The reading (hiragana) of the city name.
  - **town** (string) - The name of the town.
  - **town-kana** (string) - The reading (hiragana) of the town name.
  - **x** (string) - The longitude of the town (World Geodetic System).
  - **y** (string) - The latitude of the town (World Geodetic System).
  - **postal** (string) - The postal code for the town.
```

--------------------------------

### Get Stations

Source: https://geoapi.heartrails.com/api.html

Retrieves information about the nearest stations to a given postal code. This API is useful for location-based services.

```APIDOC
## GET /api/xml?method=getStations

### Description
Retrieves information about the nearest stations to a given postal code. This API is useful for location-based services.

### Method
GET

### Endpoint
https://geoapi.heartrails.com/api/xml?method=getStations

### Parameters
#### Query Parameters
- **method** (string) - Required - The method name, fixed as "getStations".
- **postal** (string) - Required - The URL-encoded 7-digit postal code.
- **jsonp** (string) - Optional - Callback function name for JSONP requests.

### Response
#### Success Response
- **response** (object) - Contains the list of nearest stations.
  - **station** (object) - Information about a station.
    - **name** (string) - The name of the station.
    - **kana** (string) - The reading (hiragana) of the station name.
    - **prev** (string) - The name of the previous station (null for the first station).
    - **next** (string) - The name of the next station (null for the last station).
    - **x** (string) - The longitude of the station (World Geodetic System).
    - **y** (string) - The latitude of the station (World Geodetic System).
    - **distance** (string) - The distance from the specified location to the station (accuracy of 10m).
    - **postal** (string) - The postal code of the station.
    - **prefecture** (string) - The prefecture where the station is located.
    - **line** (string) - The railway line the station belongs to.
```

--------------------------------

### HTML for Prefecture, City, and Town Selection

Source: https://geoapi.heartrails.com/api.html

HTML structure for creating linked dropdown menus for selecting Prefecture, City, and Town. Requires jQuery and the geoapi.js script.

```HTML
<head>
...
<script type="text/javascript"
  src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
<script type="text/javascript" src="https://geoapi.heartrails.com/api/geoapi.js"></script>
...
</head>
<body>
...
<select id="geoapi-prefectures" name="geoapi-prefectures">
  <option value="都道府県を選択してください">都道府県を選択してください</option>
</select>
<select id="geoapi-cities" name="geoapi-cities">
  <option value="市区町村名を選択してください">市区町村名を選択してください</option>
</select>
<select id="geoapi-towns" name="geoapi-towns">
  <option value="町域を選択してください">町域を選択してください</option>
</select>
...
</body>
...
```

--------------------------------

### Suggest Address by Keyword

Source: https://geoapi.heartrails.com/api.html

Retrieves a list of address information that matches a given keyword with specified matching type (prefix, like, suffix). Supports XML and JSON(P) formats.

```APIDOC
## POST /api/xml?method=suggest

### Description
Retrieves address information based on a keyword search with a specified matching type.

### Method
POST

### Endpoint
https://geoapi.heartrails.com/api/xml

### Parameters
#### Query Parameters
- **method** (string) - Required - 'suggest' (fixed)
- **keyword** (string) - Required - The keyword to search for (URL encoded, UTF-8).
- **matching** (string) - Required - Matching type: 'prefix' (starts with), 'like' (contains), 'suffix' (ends with).
- **jsonp** (string) - Optional - Callback function name for JSONP requests

### Request Example
```json
{
  "method": "suggest",
  "keyword": "新宿区",
  "matching": "like"
}
```

### Response
#### Success Response (200)
- **response** (array) - List of address information.
  - **prefecture** (string) - Prefecture name.
  - **city** (string) - City name.
  - **city-kana** (string) - Reading of the city name (hiragana).
  - **town** (string) - Town name.
  - **town-kana** (string) - Reading of the town name (hiragana).
  - **x** (double) - Longitude of the town area (World Geodetic System).
  - **y** (double) - Latitude of the town area (World Geodetic System).
  - **postal** (string) - Postal code of the town area.

#### Response Example
```json
{
  "response": [
    {
      "prefecture": "東京都",
      "city": "新宿区",
      "city-kana": "しんじゅくく",
      "town": "新宿",
      "town-kana": "しんじゅく",
      "x": 139.7026,
      "y": 35.6895,
      "postal": "160-0022"
    }
  ]
}
```
```

--------------------------------

### HTML for Area, City, and Town Selection

Source: https://geoapi.heartrails.com/api.html

HTML structure for creating linked dropdown menus for selecting Area, City, and Town. Requires jQuery and the geoapi.js script.

```HTML
<head>
...
<script type="text/javascript"
  src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
<script type="text/javascript" src="https://geoapi.heartrails.com/api/geoapi.js"></script>
...
</head>
<body>
...
<select id="geoapi-areas" name="geoapi-areas">
  <option value="エリアを選択してください">エリアを選択してください</option>
</select>
<select id="geoapi-cities" name="geoapi-cities">
  <option value="市区町村名を選択してください">市区町村名を選択してください</option>
</select>
<select id="geoapi-towns" name="geoapi-towns">
  <option value="町域を選択してください">町域を選択してください</option>
</select>
...
</body>
...
```

--------------------------------

### Search Address by Postal Code

Source: https://geoapi.heartrails.com/api.html

Retrieves town information corresponding to a given postal code. This API is essential for address lookup services.

```APIDOC
## GET /api/json?method=searchByPostalCode

### Description
Retrieves town information corresponding to a given postal code. This API is essential for address lookup services.

### Method
GET

### Endpoint
https://geoapi.heartrails.com/api/json?method=searchByPostalCode

### Parameters
#### Query Parameters
- **method** (string) - Required - The method name, fixed as "searchByPostalCode".
- **postal** (string) - Required - The URL-encoded 7-digit postal code.
- **jsonp** (string) - Optional - Callback function name for JSONP requests.

### Response
#### Success Response
- **response** (object) - Contains the town information.
  - **prefecture** (string) - The prefecture name.
  - **city** (string) - The city name.
  - **town** (string) - The town name.
  - **x** (string) - The longitude of the town (World Geodetic System).
  - **y** (string) - The latitude of the town (World Geodetic System.).
```

--------------------------------

### Search by Postal Code

Source: https://geoapi.heartrails.com/api.html

Retrieves address information based on a 7-digit postal code. Supports both XML and JSON(P) formats.

```APIDOC
## POST /api/xml?method=searchByPostal

### Description
Retrieves address information by postal code.

### Method
POST

### Endpoint
https://geoapi.heartrails.com/api/xml

### Parameters
#### Query Parameters
- **method** (string) - Required - 'searchByPostal' (fixed)
- **postal** (string) - Required - 7-digit postal code (URL encoded, UTF-8)
- **jsonp** (string) - Optional - Callback function name for JSONP requests

### Request Example
```json
{
  "method": "searchByPostal",
  "postal": "0010010"
}
```

### Response
#### Success Response (200)
- **response** (array) - List of address information.
  - **prefecture** (string) - Prefecture name.
  - **city** (string) - City name.
  - **city-kana** (string) - Reading of the city name (hiragana).
  - **town** (string) - Town name.
  - **town-kana** (string) - Reading of the town name (hiragana).
  - **x** (double) - Longitude of the town area (World Geodetic System).
  - **y** (double) - Latitude of the town area (World Geodetic System).
  - **postal** (string) - Postal code of the town area.

#### Response Example
```json
{
  "response": [
    {
      "prefecture": "北海道",
      "city": "札幌市",
      "city-kana": "さっぽろし",
      "town": "北一条",
      "town-kana": "きたじょう",
      "x": 141.3540,
      "y": 43.0679,
      "postal": "001-0010"
    }
  ]
}
```
```

--------------------------------

### HTML for Postal Code and Address Search Form

Source: https://geoapi.heartrails.com/api.html

HTML structure for a form that allows users to input a postal code and automatically complete the address. Requires jQuery and the geoapi.js script.

```HTML
<head>
...
<script type="text/javascript"
  src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
<script type="text/javascript" src="https://geoapi.heartrails.com/api/geoapi.js"></script>
...
</head>
<body>
...
<input id="geoapi-postal-3" name="geoapi-postal-3" type="text" maxlength="3" />
<input id="geoapi-postal-4" name="geoapi-postal-4" type="text" maxlength="4" />
<input id="search-by-postal" name="search-by-postal" type="submit" value="検索する" />
<input id="geoapi-address" name="geoapi-address" type="text" />
...
</body>
...
```

--------------------------------

### Search by Geo Location

Source: https://geoapi.heartrails.com/api.html

Retrieves address information for town areas near a specified longitude and latitude. Supports XML and JSON(P) formats.

```APIDOC
## POST /api/xml?method=searchByGeoLocation

### Description
Retrieves address information near a specified geographic location (longitude and latitude).

### Method
POST

### Endpoint
https://geoapi.heartrails.com/api/xml

### Parameters
#### Query Parameters
- **method** (string) - Required - 'searchByGeoLocation' (fixed)
- **x** (double) - Required - Longitude of the location (World Geodetic System).
- **y** (double) - Required - Latitude of the location (World Geodetic System).
- **jsonp** (string) - Optional - Callback function name for JSONP requests

### Request Example
```json
{
  "method": "searchByGeoLocation",
  "x": 135.0,
  "y": 35.0
}
```

### Response
#### Success Response (200)
- **response** (array) - List of address information.
  - **prefecture** (string) - Prefecture name.
  - **city** (string) - City name.
  - **city-kana** (string) - Reading of the city name (hiragana).
  - **town** (string) - Town name.
  - **town-kana** (string) - Reading of the town name (hiragana).
  - **x** (double) - Longitude of the town area (World Geodetic System).
  - **y** (double) - Latitude of the town area (World Geodetic System).
  - **postal** (string) - Postal code of the town area.

#### Response Example
```json
{
  "response": [
    {
      "prefecture": "兵庫県",
      "city": "神戸市",
      "city-kana": "こうべし",
      "town": "中央区",
      "town-kana": "ちゅうおうく",
      "x": 135.1957,
      "y": 34.6901,
      "postal": "650-0000"
    }
  ]
}
```
```
Tokens:
Raw