Ekispert (駅すぱあと)API_Gợi ý cho bài toán chức năng tìm đường và tính toán phí giao thông ở Nhật. (Phần 1)

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

Item
API Endpoint
SSL Support
HTTP method có thể sử dụng
response data format có thể sử dụng

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.

format Content-Type
xml application/xml;charset=utf-8
json Trường hợp chỉ application/json, application/* application/json;charset=utf-8
Trường hợp chỉ text/plain, text/* text/plain;charset=utf-8 .
Trường hợp * / * , chưa chỉ địnhtext/plain;charset=utf-8

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>JR新幹線のぞみ</Name>
  </Line>
  <Point index="2">
    <Station code="25978">
      <Name>新大阪</Name>
    </Station>
  </Point>
  <Line index="2">
    <Name>JR東海道本線・西明石行</Name>
  </Line>
  <Point index="3">
    <Station code="25853">
      <Name>大阪</Name>
    </Station>
  </Point>
</Route>
"Route": {
  "Point": [
    {
      "Station": {
        "Name": "東京",
      }
    },
    {
      "Station": {
        "Name": "新大阪",
      }
    },
    {
      "Station": {
        "Name": "大阪",
      }
    }
  ],
  "Line": [
    {
      "Name": "JR新幹線のぞみ",
    },
    {
      "Name": "JR東海道本線・西明石行",
    }
  ],
}

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

Name Type Description
format string Chỉ định dạng data của response. Bắt buộc.
Giá trị có thể chỉ định:
- xml: Data dạng xml
- json: Data dạng json
key string accesskey(アクセスキー). Bắt buộc
viaList string Danh sách mã ga (station code), tên ga (station name), thông tin tọa độ (coordinate infomation) hoặc là data địa điểm... Có thể multipe chỉ định. Mức tối đa là 20 cái. Bắt buộc.
fixedRailList string Cố định danh sách tên của tuyến đường trung bình. Chỉ hữu hiệu với trường hợp searchType là plain. Có thể giản lược. Khi giản lược thì tuyến đường không cố định.
fixedRailDirectionList string Cố định danh sách phương hướng của tuyến đường trung bình. Chỉ hữu hiệu khi chỉ định ở searchType là plain và chỉ định fixedRailList. Có thể giản lược. Khi giản lược thì tự động phán đoán phương hướng.
date int Ngày tìm kiếm. Có thể giản lược.
Format: YYYYMMDD
Default: Ngày hiện tại
time int Thời gian tìm kiếm. Có thể giản lược.
Format: HHMM
Default:Ngày hiện tại
searchType string Phân loại tìm kiếm. Có thể giản lược.
Giá trị có thể chỉ định:
- departure : Tìm giờ xuất phát
- arrival: Tìm giờ đến
- lastTrain: Tìm tuyến tàu cuối
- firstTrain: Tìm tuyến đầu tiên
- plain: Tìm thời gian chờ trung bình.
Default: departure
sort string Phân loại sort. Có thể giản lược.
Giá trị có thể chỉ định:
- ekispert: Theo tìm kiếm với ekispert (駅すぱあと)
- price: Theo tiền phí
- time: Theo thời gian
- teiki: Theo số tiền phí vé định kỳ
- transfer: Theo số lần chuyển tàu
- co2: Theo lượng thải khí CO2
- teiki1: Theo số tiền phí của vé định kỳ 1 tháng
- teiki3: Theo số tiền phí của vé định kỳ 3 tháng
- teiki6: Theo số tiền phí của vé định kỳ 6 tháng
Default: ekispert
answerCount int Số trả lời tối đa. Max là 20. Có thể giản lược.
Default: 5
searchCount int Số tìm kiếm tối đa. Max là 20. Có thể giản lược.
Default: setting giá trị giống answerCount
conditionDetail string Data điều kiện tìm kiếm chi tiết. Sử dụng loại phương tiện giao thông và có hay không tính toán cước phí IC, Loại chổ của số tiền siêu tốc trả về như là giá trị ban đầu, có thể chỉ định thời gian chuyển tàu... Có thể giản lược.
Default: T3221233232319:F3321122120:A23121141:
corporationBind string Cố định tên công ty. Chỉ sử dụng công ty đã chỉ định. Có thể multipe chỉ định. Max là 10 cái. Có thể giản lược. Khi giản lược thì không giới hạn mà thành tìm kiếm bình thường.
interruptCorporationList string Danh sách công ty không hợp. Tìm kiếm tuyến đường không sử dụng công ty đã chỉ định. Chỉ hữu hiệu khi searchType là plain. Có thể giản lược. Khi giản lược thì không giới hạn mà thành tìm kiếm bình thường.
interruptRailList string Danh sách tuyến đường trung bình không hợp. Tìm kiếm tuyến đường không sử dụng tuyến đường trung bình đã chỉ định. Chỉ hữu hiệu khi searchType là plain. Có thể giản lược. Khi giản lược thì không giới hạn mà thành tìm kiếm bình thường.
resultDetail string Thêm thông tin chi tiết vào kết quả. Có thể giản lược. Khi giản lược thì thành kết quả bình thường.
Giá trị có thể chỉ định:
- addCorporation: Thêm công ty ở truyến đường
addOperationLinePattern string Thêm pattern tuyến đường vận hành liên kết với khoảng cách của tuyến đường ở kết quả. Chỉ hữu hiệu khi tìm kiếm bằng diagram. Có thể giản lược.
Giá trị có thể chỉ định:
- true: Thêm
- false: Không thêm
Default: false
assignRoute string Chuổi ký tự tuyến đường dùng phân bổ định kỳ. Liệt kê của Tên ga: tuyến đường trung bình: tên ga ...Có thể giản lược. Bài trừ với assignDetailRoute
Example: 高円寺:JR中央線快速:新宿:JR山手線外回り:池袋
assignDetailRoute string Chuỗi ký tự tuyến đường chi tiết dùng để phân bổ định kỳ. Liệt kê của Tên ga: tuyến đường trung bình: phương hướng: tên ga...Có thể giản lược. Bài trừ với assignRoute
Example: 高円寺:JR中央線快速:Up:新宿:JR山手線外回り:Down:池袋
assignNikukanteikiIndex int Trường hợp tuyến đường dùng phân bổ định kỳ là 2 khoảng cách định kỳ thì chỉ định PassStatusIndex biểu hiện trạng thái đó. Có thể multipe chỉ định. Khi multipe chỉ định nếu đã chỉ định index của khoảng cách giống nhau thì sẽ áp dụng 1 cái bất kỳ. Có thể giản lược. Khi giản lược thì tuyến đường phân bổ định kỳ thì được định kỳ bình thường.
coupon string Tên chi tiết vé số lần phân bổ. Có thể giản lược.
bringAssignmentError string Lỗi ở trường hợp error phân bổ. Ở phân bổ của vé số lần và định kỳ trong tìm kiếm tuyến đường thông thường thì, trường hợp không được phân bổ cũng không error mà trả về kết quả tìm kiếm tuyến đường. Bằng việc chỉ định true thì trường hợp ko phân bổ thì trả về error. Có thể lược bỏ.
Giá trị có thể chỉ định:
- true: Phát sinh error phân bổ
- false: Không phát sinh error phân bổ
Default: false
gcs string Trường hợp trong request và response bao gồm tọa độ, thì có thể chỉ định hệ trắc địa cảu tọa độ. Ngoài ra, thông tin tọa độ của request parameter thì có thể chỉ định cá biệt khác với parameter gcs. Có thể giản lược.
Giá trị có thể chỉ định:
- tokyo: Hệ trắc địa Nhật Bản
- wgs84: Hệ trắc địa thế giới
Default: tokyo

Tham khảo

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