利用上の注意

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

「駅すぱあとWebサービス」では、XMLの仕様に基づいて、後方互換性を維持した機能追加を行っています。 そのため、現在、単体で返る要素が複数返るようになったり、階層が異なる同じ要素名が追加されたりすることがあります。 XML形式のレスポンスデータを利用する際は、必ず以下3点の項目をご確認ください。

1. 要素の数

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

  • 要素が単体で返る
  • 要素が複数で返る
  • 要素自体返さない

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

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

3. 要素の順番

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

  :
  <Corporation index="1">
    <Name>JR</Name>
  </Corporation>
  :

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

JSON形式はXML形式と互換性がないので、仕様が異なる部分があります。 JSON形式のレスポンスデータを利用する際は、必ず以下2点の項目をご確認ください。

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

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

ある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設定について

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

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

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

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

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