はじめに
Tips一覧
定期券
探索(運賃)
探索(探索結果)
探索(探索条件)
探索(地点)
探索(路線)
路線図

定期情報の取得と更新

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

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


 Attention!

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

関連URL

手順

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

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>高円寺--JR中央線快速--新宿--JR山手線内回り--渋谷</DisplayRoute>
    </Teiki>
    <SerializeData> ... </SerializeData>
  </Course>
</ResultSet>

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

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

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

2.定期経路シリアライズデータを再登録する

定期経路シリアライズデータが再現できなくなる場合があります。

1で保存しておいた値(定期経路の表示用文字列)の発着駅を利用して、再度経路探索を行います。

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

定期経路文字列」の場合

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

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

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

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

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>JR中央線快速</Name>
          :
      <Point index="2">
        <Station code="22741">
        <Name>新宿</Name>
          :
      <Line direction="Down" stopStationCount="2" index="2" ... >
        <Name>JR山手線内回り</Name>
          :
      <Point index="3">
        <Station code="22715">
        <Name>渋谷</Name>
          :
    </Route>
      :
    <Teiki>
      <SerializeData>...</SerializeData>
      <DisplayRoute>高円寺--JR中央線快速--新宿--JR山手線内回り--渋谷</DisplayRoute>
      <!-- 定期経路文字列 -->
      <DetailRoute>高円寺:JR中央線快速:Up:新宿:JR山手線内回り: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 の 文字列を : でつなげて、 高円寺:JR中央線快速:Up:新宿:JR山手線内回り:Down:渋谷 という定期経路文字列を作成します。


 Attention!

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

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

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

2. 定期経路文字列を再取得する

定期経路文字列が再現できなくなる場合があります。
再現ができなくなる場合には、定期経路文字列を更新する必要があります。

更新の必要有無は、控除計算の実行時にbringAssignmentErrorパラメータを利用してすることで検知できます。 定期情報の再現エラー(E152)となった場合に更新してください。

bringAssignmentErrorパラメータの利用方法については、定期券利用時の運賃計算の「「定期経路文字列」の場合」の項目をご確認ください。

路線・方向を固定して再取得する場合

経路探索/search/course/extremefixedRailListパラメータとfixedRailDirectionListパラメータを利用することで、路線と方向を固定して平均探索を行うことができます。

■ 定期経路文字列例

高円寺:JR中央線快速:Up:新宿:JR山手線内回り:Down:渋谷

定期経路文字列を以下のように分解して再探索します。

  • viaList=高円寺:新宿:渋谷
  • fixedRailList=JR中央線快速:JR山手線内回り
  • fixedRailDirectionList=Up:Down

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

GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&viaList=高円寺:新宿:渋谷&searchType=plain&fixedRailList=JR中央線快速:JR山手線内回り&fixedRailDirectionList=Up:Down