定期情報の取得

定期情報の作成を行います。

Attention!

定期情報を利用することができる経路は鉄道のみです。

手順

「定期経路シリアライズデータ」の場合

1.定期経路シリアライズデータを取得する

まず、定期券の経路自体を経路探索します。

※ リクエスト例では日本語で記述しておりますが、リクエストパラメータに日本語が含まれる場合には、日本語の部分をUTF8でURLエンコード(パーセントエンコード)してください。

GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&viaList=高円寺:渋谷

<?xml version="1.0" encoding="UTF-8"?>
<ResultSet apiVersion="1.27.0.0" engineVersion="201806_02a">
  <Course searchType="departure" dataType="onTimetable">
    <Route index="1" transferCount="1" ...>
      :
    </Route>
    <Teiki>
      <!-- 定期経路シリアライズデータ -->
      <SerializeData>VkV4QaECp_rHAQEDpgEz7osEk8EBpViPwQGlWNXBAaVYuwWSwwEBA6RtBKVY1cQBAQIBA6RxBKVYuweRxQGlWI8CpVi7AwAEAQUACAEKAQ**--2ffa318938ac7a409fec1643d23af692c573ee53--0--79</SerializeData>
      <!-- 定期経路の表示用文字列 -->
      <DisplayRoute>高円寺--ＪＲ中央線快速--新宿--ＪＲ山手線内回り--渋谷</DisplayRoute>
    </Teiki>
    <SerializeData> ... </SerializeData>
  </Course>
</ResultSet>

定期情報を利用することができる経路の場合に、 /ResultSet/Course/Teiki/SerializeData （定期経路シリアライズデータ）が返されます。「定期経路の表示用文字列」も定期経路シリアライズデータとセットで保存しておきます。

※ 保存の必要性については、定期経路シリアライズデータの取得についてをご確認ください。

定期情報の利用は定期券利用時の運賃計算をご確認ください。

Attention!

駅や路線は、新設や廃止があるため、定期情報の定期的な更新を推奨しております。詳しくは定期情報の更新をご確認ください。

「定期経路文字列」の場合

1.定期経路文字列を取得する。

まず、定期券の経路自体を平均待ち時間による探索で経路探索します。
ダイヤによる探索では定期経路文字列を作成することはできません。

リクエスト例では経路探索/search/course/extreme を利用していますが、平均待ち時間による探索を行うことができるAPI（経路簡易探索、平均待ち時間探索）でも可能です。

GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&viaList=高円寺:渋谷&searchType=plain

<?xml version="1.0" encoding="UTF-8"?>
<ResultSet apiVersion="1.27.0.0" engineVersion="201806_02a">
  <Course searchType="plain" dataType="plain">
    <Route index="1" transferCount="1" ...>
      <Point index="1">
        <Station code="22671">
        <Name>高円寺</Name>
          :
      <Line direction="Up" stopStationCount="1" index="1" ... >
        <Name>ＪＲ中央線快速</Name>
          :
      <Point index="2">
        <Station code="22741">
        <Name>新宿</Name>
          :
      <Line direction="Down" stopStationCount="2" index="2" ... >
        <Name>ＪＲ山手線内回り</Name>
          :
      <Point index="3">
        <Station code="22715">
        <Name>渋谷</Name>
          :
    </Route>
      :
    <Teiki>
      <SerializeData>...</SerializeData>
      <DisplayRoute>高円寺--ＪＲ中央線快速--新宿--ＪＲ山手線内回り--渋谷</DisplayRoute>
      <!-- 定期経路文字列 -->
      <DetailRoute>高円寺:ＪＲ中央線快速:Up:新宿:ＪＲ山手線内回り:Down:渋谷</DetailRoute>
    </Teiki>
    <SerializeData> ... </SerializeData>
  </Course>
</ResultSet>

定期情報を利用することができる経路の場合に、ResultSet/Course/Teiki/DetailRoute （定期経路文字列）が返されます。

定期経路文字列は、お客様のアプリケーション側で、ResultSet/Course/Route 下の駅名や路線名を文字列連結して作成することも可能です。

Attention!

定期経路文字列をお客様側で作成する場合は、アプリケーション側で、定期券として利用可能かどうかの判定を行っていただくことを推奨しています。
作成した定期経路文字列は、定期券として利用可能な経路かどうかに関わらず、当てはまる区間があれば運賃が控除できますが、定期券を利用した運賃計算で保証するのは、交通種別が鉄道の経路のみとなります。

定期経路文字列の作成方法

駅の名称 ResultSet/Course/Route/Point/Station/Name と、平均路線 ResultSet/Course/Route/Line/Name と、平均路線の方向 ResultSet/Course/Route/Line/direction の文字列を : でつなげて、 高円寺:ＪＲ中央線快速:Up:新宿:ＪＲ山手線内回り:Down:渋谷 という定期経路文字列を作成します。

Attention!

定期経路文字列の駅の名称、平均路線と平均路線の方向は、必ず正しい名称を指定してください。
「駅すぱあと」に存在しない駅の名称や平均路線を指定してしまったり、順序が正しくないと、意図しない定期券経路が利用される可能性があります。

正) 高円寺:ＪＲ中央線快速:Up:新宿:ＪＲ山手線内回り:Down:渋谷
誤) 高円寺:JR中央線快速:Up:新宿:ＪＲ山手線内回り:Down:渋谷
誤) 高円寺:ＪＲ中央線快速:Up:新宿:ＪＲ山手線:Down:渋谷
誤) 高円寺:ＪＲ中央線快速・東京行:Up:新宿:ＪＲ山手線内回り:Down:渋谷