利用上の注意

はじめに

「駅すぱあと API」は、既存の利用者様に問題なくサービスをご利用いただけるように、後方互換性を維持した機能追加を行っております。そのため、今後の機能追加によっては、現在は単体で返っている要素が、今後は複数の要素で返るようになったり、階層が異なる同じ要素名が新たに追加されるようなことがございます。予めご了承ください。

XML形式のレスポンスデータを利用する際の注意事項

XML形式のレスポンスデータを利用する際は、必ず以下の3点をご確認ください。

1. 要素の数

XMLでは同じ階層に同名の要素が複数存在することが可能です。要素を取得する場合には、現行の仕様にかかわらず常に複数取得できることを想定して実装してください。例えば、経路探索/search/course/extremeのレスポンスResultSet/Course/PassStatus要素は、探索した経路によって下記のようなバリエーションが考えられます。

※ 経路探索は、スタンダードプランの機能です。

要素が単体で返る

<Course>
    :
  <PassStatus ...>
    <Name>ＩＣ定期</Name>
  </PassStatus>
    :
<Course>

要素が複数で返る

<Course>
    :
  <PassStatus ...>
    <Name>一般定期</Name>
  </PassStatus>
  <PassStatus ...>
    <Name>全線定期</Name>
  </PassStatus>
    :
</Course>

要素自体返さない

<Course>
  <!-- 一般定期しか存在しない経路の場合、PassStatus要素自体が返らない -->
   :
<Course>

2. 要素、属性のパス指定

XMLの要素と属性は最上位からのパスを含めて識別されるため、パスを指定する場合には、相対パスではなく絶対パスで指定してください。

3. 要素の順番

XMLの要素は順序が一定となることを保証していません。順序に意味のある要素は、index属性を利用して並び替えてください。

  :
  <Corporation index="1">
    <Name>ＪＲ</Name>
  </Corporation>
  :

JSON形式のレスポンスデータを利用する際の注意事項

JSON形式のレスポンスデータを利用する際は、必ず以下の3点をご確認ください。

1. キーに対する値のバリエーション

JSON形式において、キーに対する値は、1つのオブジェクトである場合や、オブジェクトからなる配列である場合があります。また、キーと値自体が存在しない場合もあります。
現在オブジェクトで返される値であっても、将来的に配列で返されるようになる可能性もあるため、各キーがとりうる値の構造（「オブジェクト」または「配列」）を一覧で提示することはできません。
取得した値のバリエーションにかからわず処理できるように、「取得したキーに対する値が存在するかどうかをチェックする処理」、「値のクラスを参照し、配列でない場合は配列に格納する処理」などの実装を推奨します。
例えば、経路探索/search/course/extremeのレスポンスResultSet/Course/PassStatusの値は、探索した経路によって下記のようなバリエーションが考えられます。

※ 経路探索は、スタンダードプランの機能です。

値がオブジェクトで返る

{
  "PassStatus": {
    "Name": "ＩＣ定期",
  },
  :
}

値が配列で返る

{
  "PassStatus": [
    {
      "Name": "一般定期",
    },
    {
      "Name": "全線定期",
    }
  ],
  :
}

キーと値自体が返らない

{
  ## 一般定期しか存在しない経路の場合、PassStatusのキーと値自体が返らない
  :
}

2. indexの扱い

XMLで要素別の順番を表している"index"属性は、json形式のレスポンスには含まれません。同名要素が同じ階層に複数存在する場合、jsonでは要素名でまとめた配列としてデータが返されます。また、"xxxIndex"といったindex関連の値は、xmlのindexを基準にしています。 xmlのindexは1から始まりますが、jsonの配列は0から始まるため、値にズレが生じます。jsonでindex関連の値を扱う際はご注意ください。

<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": "ＪＲ東海道本線・西明石行",
    }
  ],
}

3. テキストノードの扱い

あるxmlの要素がテキストノードのみを持っている場合、 jsonではそのテキストノードの内容を該当の要素名の値として設定します。

<Type>train</Type>

{"Type": "train"}

テキストノードを持つxmlの要素が子要素や属性も持っている場合、 jsonではそのテキストノードの内容を"text"の値として設定します。

<Type detail="local">bus</Type>

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

URLエンコードに関する注意

リクエストパラメータに日本語またはパイプ|が含まれる場合には、 UTF8でURLエンコード(パーセントエンコード)してください。ただし、コロン:やスラッシュ/など、RFC3986で定義された予約文字は、URLエンコードしないでください。

# GET /v1/xml/station?key=xxx&viaList=高円寺:新宿:池袋
GET /v1/xml/station?key=xxx&name=%e9%ab%98%e5%86%86%e5%af%ba:%e6%96%b0%e5%ae%bf:%e6%b1%a0%e8%a2%8b

DNSのTTL設定について

「駅すぱあと API」を利用する際には、DNSのTTLを適切に設定してください。 TTLとは、DNSに対して、パケットをキャッシュとして保持する時間を設定するパラメータです。 DNSのTTLを正しく設定しないと、システム障害が起こる可能性があります。「駅すぱあと API」が推奨するTTL設定は６０秒です。意図しないキャッシュにご注意いただくと共に、アプリケーション側の設定を今一度ご確認お願いします。

Javaで開発を行っている方へ

Tomcatを利用してアプリケーション開発を行っている場合、セキュリティマネージャをONに設定することでDNSキャッシュが無期限になります。セキュリティマネージャがONになっていないか、今一度ご確認お願いします。

グローバルIPアドレスについて

「駅すぱあと API」のグローバルIPアドレスは複数存在し、かつ可変となっております。 IP制限等の制御を行うことは出来ませんのでご注意ください。

タイムゾーンについて

「駅すぱあと API」では、リクエスト、レスポンス共に日本標準時として扱っています。