Giới thiệu

Bạn đang xây dựng hệ thống cho công ty, web site hay là app smartphone cho khách hàng Nhật Bản. Và họ có mong muốn add thêm chức năng tìm kiếm đường đi hay thanh toán kinh phí giao thông...vào. Nhưng để phát triển chức năng đó thì cần tốn nhiều kinh phí và thời gian vượt bugket của dự án. Vậy một trong những lựa chọn hàng đầu cho dự án bạn là sử dụng service của bên thứ 3. Ở đây mình gửi đến bạn gợi ý là sử dụng Ekispert (駅すぱあと) API. Document về API thì có khá chi tiết nhưng lại viết hoàn toàn bằng tiếng Nhật. Đối với những dev không đọc được tiếng Nhật thì việc implement có gặp nhiều khó khăn nên mình sẽ tóm tắt lại thành bản tiếng Việt để chia sẽ.

Khái quát API

Khái quát

Spec chi tiết của API

Content-Type của response header

Format của từng Content-Type của response header thì sẽ trả về giá trị như bên dưới. Trường hợp json thì giá trị trả về thay đổi theo Accept của request header.

Trường hợp chỉ định tiếng Nhật ở request parameter

Trường hợp trong request parameter có bao gồm tiếng Nhật thì, hãy encode URL bằng UTF8 (Percent encode) phần tiếng nhật. GET /v1/xml/station?key=xxx&name=%93%8c%8b%9e

Multipe chỉ định

Trong request parameter của các API thì có cho phép đa chỉ định. Trường hợp multipe chỉ định paramater đó thì hãy ghi phân cách giá trị bằng dấu hai chấm ( code=22828:22741

Xử lý index trong json

Thuộc tính index ở XML thì trong response của dạng json ko có. Trường hợp tồn tại nhiều element cùng tên ở cùng cấp thì ở json trả về data array đã tập hợp tóm tắt tên element. Ngoài ra, giá trị của index ví dụ như "xxxIndex" thì đang base theo index của xml. index của xml thì bắt đầu từ 1 nhưng array của json thì bắt đầu từ 0 nên sinh ra lệch giá trị. Hãy chú ý khi xử lý giá trị của index ở json.

<Route>
  <Point index="1">
    <Station code="22828">
      <Name>東京</Name>
    </Station>
  </Point>
  <Line index="1">
    <Name>ＪＲ新幹線のぞみ</Name>
  </Line>
  <Point index="2">
    <Station code="25978">
      <Name>新大阪</Name>
    </Station>
  </Point>
  <Line index="2">
    <Name>ＪＲ東海道本線・西明石行</Name>
  </Line>
  <Point index="3">
    <Station code="25853">
      <Name>大阪</Name>
    </Station>
  </Point>
</Route>

"Route": {
  "Point": [
    {
      "Station": {
        "Name": "東京",
      }
    },
    {
      "Station": {
        "Name": "新大阪",
      }
    },
    {
      "Station": {
        "Name": "大阪",
      }
    }
  ],
  "Line": [
    {
      "Name": "ＪＲ新幹線のぞみ",
    },
    {
      "Name": "ＪＲ東海道本線・西明石行",
    }
  ],
}

Xử lý text node trong json

Trường hợp element của xml đang chỉ có text node thì trong json setting giá trị của tên element tương ứng nội dung của text node đó. <Type>train</Type>

{"Type": "train"}

Trường hợp element của xml có text node có cả subelement và attribute thì trong json setting như là giá trị của "text" nội dung text node đó. <Type detail="loccal">bus</Type>

{
  "Type": {
    "detail": "local",
    "text": "bus"
  }
}

Error

Error của API「駅すぱあとWebサービス」thì đang biểu hiện bằng message bao gồm error của HTTP protocol và error response. Mã lỗi nội bộ (internal error code_内部エラーコード) thì nó sẽ trở thành thông tin tham khảo sử dụng khi hổ trợ.

<?xml version="1.0" encoding="UTF-8"?>
<ResultSet apiVersion="1.x.x.x" engineVersion="xxxxxx_xxx">
  <Error code="内部エラーコード">
    <Message>エラーメッセージ</Message>
  </Error>  
</ResultSet>

API lists

Tìm kiếm

Tìm kiếm tuyến đường (経路探索)

Chỉ định ga hoặc là địa điểm rồi có thể tìm kiếm đường đi sử dụng phương tiện giao thông công cộng. GET /v1/{format}/search/course/extreme

parameters

Tham khảo

http://docs.ekispert.com/v1/api/