JA:Xapi

From OpenStreetMap Wiki
Jump to navigation Jump to search
Logo.png
This page describes a historic artifact in the history of OpenStreetMap. It does not reflect the current situation, but instead documents the historical concepts, issues, or ideas.日本語の翻訳にご協力ください！


Xapi - Other languages

an unequal sign

この記事は「日本語版」として翻訳されていますが、原文（通常、英語版またはドイツ語版）の変更が反映されていないようです。できればこの翻訳の更新にご協力ください。

OSMの拡張 API（別名xapi,ザッピーと読みます）は標準APIをベースに開発された、より高度な検索機能を備えた読み込み専用のAPIです。標準の地図のリクエストとタグの値による検索クエリを実装しています。 データベースはOSMのメインデータベースの複製で、毎分diffを使って更新されています。メインデータベースより10分以内の遅れで追従しているといえるでしょう。 Xapiでは X-path 風な REST 形式のインターフェースを使用します。

すべてのレスポンスは標準プロトコルと同じフォーマットに、名前空間を拡張したものを用います。X-path風のクエリは検索単語の指定に使用します。

サーバ Servers

Xpaiのサービスはいくつものサーバで実行されています。それぞれのサーバにも直接接続も可能ですが、 informationfreeway にリクエストを送ると、選択に応じて適切なサーバに転送されます。

マップクエリ

マップクエリは標準APIと全く同じクエリ、応答を返します。

  • 指定した範囲 (bbox) に含まれるすべてのノードとそれらノードを含む全てのリレーションを返します。
  • 指定した範囲 (bbox) のノードを1つは持っているすべてのウェイと、それらウェイを含む全てのリレーション、それらウェイが参照している範囲外のノードを返します。
GET /api/0.6/map?bbox=left,bottom,right,top

とすると

  • left bbox の左端にあたる経度（西端）
  • bottom bbox の下端にあたる緯度（南端）
  • right bbox の右端にあたる経度（東端）
  • top bbox の上端にあたる経度（北端）
上 top
下 bottom
左 left
右 right
東 right
西 left
南 bottom
北 top

例

http://www.informationfreeway.org/api/0.6/map?bbox=11.54,48.14,11.543,48.145

メモ

  • 標準APIでは0.25平方度以上の範囲のリクエストを制限していますが、XAPIではもっとずっと広い 最大10,000,000要素(これはカリフォルニアの1/3未満です。) 又は、100平方度のどちらか小さい方まで対応しています。
  • マップクエリと同じことをタグクエリでも実行できます。/api/0.6/*[bbox=left,bottom,right,top]
  • There must not be spaces in the string of values defining the box.

タグクエリ

Xapi はすべての要素（ノード、ウェイ、リレーション）に関するタグを検索する機能を備えています。

ノード

ノードリクエストはノードとそれに属するタグを含んだ xml を返します。ノードリクエストのURLは以下の形式をとります: 

http://www.informationfreeway.org/api/0.6/node[...]

これはノードとタグを含む標準OSM API 応答を返します。例えば: 

  <?xml version='1.0' standalone='no'?>
  <osm version='0.6' generator='xapi: OSM Extended API' 
   xmlns:xapi='<nowiki>http://www.informationfreeway.org/xapi/0.6</nowiki>'
   xapi:uri='/api/0.6/node[amenity=hospital]'
   xapi:planetDate='200803150826' 
   xapi:copyright='2008 OpenStreetMap contributors' 
   xapi:instance='zappy2'>
    <node id='672180' lat='48.2111685091189' lon='16.3035366605548' timestamp='2006-09-11T16:28:25+01:00' version='1' changeset='10968'>
      <tag  k='amenity' v='hospital'/>
      <tag  k='name' v='Wilhelminenspital'/>
    </node>
    <node id='3596186' lat='53.4633699598014' lon='-2.22667910006381' timestamp='2007-06-21T17:10:58+01:00' version='2' changeset='2213'>
      <tag  k='amenity' v='hospital'/>
      <tag  k='name' v='Manchester Royal Infirmary'/>
    </node>
    ...
  </osm>

ウェイ

ウェイをリクエストするURLは次の形式です: 

http://www.informationfreeway.org/api/0.6/way[...]

このリクエストでは、[...]に指定した検索語に該当したウェイを含むXMLを返します。該当したウェイに1つ1つに対して、そのウェイによって参照されているノードも返ってきます。 ウェイクエリからの応答の例は、以下の通りです。: 

  <?xml version='1.0' standalone='no'?>
  <osm version='0.6' generator='xapi: OSM Extended API' 
   xmlns:xapi='<nowiki>http://www.informationfreeway.org/xapi/0.6</nowiki>'
   xapi:uri='/api/0.6/way[landuse=residential]'
   xapi:planetDate='200803150826' 
   xapi:copyright='2008 OpenStreetMap contributors' 
   xapi:instance='zappy2'>
    <way id='4958218' timestamp='2007-07-25T01:55:35+01:00' version='3' changeset='2211'>
      <nd ref='218963'/>
      <nd ref='331193'/>
      ...
      <tag  k='landuse' v='residential'/>
      <tag  k='source' v='landsat'/>
    </way>
  </osm>

リレーション

リレーションのリクエストURLは次の形式です: 

http://www.informationfreeway.org/api/0.6/relation[...]

これは、検索した語に該当したリレーションを含むXMLを返します。該当したリレーションに対して、そのリレーションに参照されているノードとウェイも返ってきます。リレーションクエリー応答の例は以下になります: 

  <?xml version='1.0' standalone='no'?>
  <osm version='0.6' generator='xapi: OSM Extended API' 
   xmlns:xapi='<nowiki>http://www.informationfreeway.org/xapi/0.6</nowiki>'
   xapi:uri='/api/0.6/way[landuse=residential]'
   xapi:planetDate='200803150826' 
   xapi:copyright='2008 OpenStreetMap contributors' 
   xapi:instance='zappy2'>
    <relation id='2670' timestamp='2007-10-25T03:05:34Z' version='32' changeset='2211'>
      <member type='way' ref='3992472' role=''/>
      <member type='way' ref='3992524' role=''/>
      <member type='way' ref='4253050' role=''/>
      <member type='way' ref='4253053' role=''/>
      <member type='way' ref='4266813' role=''/>
      <member type='way' ref='10285106' role=''/>
      <tag k='name' v='Fonnereau Way'/>
      <tag k='network' v='Ipswich footpaths'/>
      <tag k='type' v='route'/>
    </relation>    
  </osm>

すべての要素

ノード、ウェイ、リレーションの全てに対して、述語フィルターによる検索を行うには、以下URLを使います。: 

 http://www.informationfreeway.org/api/0.6/*[...]

このリクエストは、検索語に該当したノード、ウェイ、リレーションを含むXMLを返します。それぞれの該当したウェイに対して、ノードとそのウェイによって参照されているノードも一緒に返ってきます。同様に、該当したリレーションに1つ1つに対しても、それに参照されているウェイとノードが返ってきます。 この種のクエリーに対する応答の例は次のようになります。: 

  <?xml version='1.0' standalone='no'?>
  <osm version='0.6' generator='xapi: OSM Extended API' 
   xmlns:xapi='<nowiki>http://www.informationfreeway.org/xapi/0.6</nowiki>'
   xapi:uri='/api/0.6/*[amenity=hotel]'
   xapi:planetDate='200803150826' 
   xapi:copyright='2008 OpenStreetMap contributors' 
   xapi:instance='zappy2'>
    <node id='218963' lat='52.5611324692581' lon='-1.79024812573334' timestamp='2006-03-22T16:47:48+00:00' version='1' changeset='2211'>
    </node>
    <node id='331193' lat='53.7091237972264' lon='-1.50282510180841' timestamp='2007-03-31T00:09:22+01:00' version='1' changeset='2211'>
      <tag k='amenity' v='hotel'/>
    </node>
    ... 
    <way id='4958218' timestamp='2007-07-25T01:55:35+01:00' version='1' changeset='2211'>
      <nd ref='218963'/>
      <nd ref='331193'/>
      ...
      <tag k='amenity' v='hotel'/>
      <tag k='building' v='hotel'/>
    </way>
    <relation id='123456' timestamp='2007-10-25T03:05:34Z' version='32' changeset='2211'>
      <member type='node' ref='331193' role=''/>
      <member type='node' ref='331194' role=''/>
      ...
      <tag k='amenity' v='hotel'/>
      <tag k='operator' v='Premier Inns'/>
      <tag k='type' v='operators'/>
    </relation>    
  </osm>

述語 Predicates

APIリクエストでは述語を指定して選択する要素を指定することができます。たとえば[amenity=hospital]を指定すると指定範囲内の病院、amenity=hospitalのタグを持つものだけを返します。 Each API request can be suffixed with selection predicates which determine which elements to select. For example [amenity=hospital] will select all elements that have an amenity tag with a value of hospital. The full url to select all nodes that are tagged as hospitals would be: 

 http://www.informationfreeway.org/api/0.6/node[amenity=hospital]

今のところbbox内のタグ一つだけに対応しています。 A request can be suffixed with multiple predicates, each of which further constrains the results (currently limited to one tag predicate and one bbox predicate). For example: 

 http://www.informationfreeway.org/api/0.6/node[amenity=hospital][bbox=-6,50,2,61]

この応答は指定したbbox内（例ではイギリス全土）の病院すべてのタグを返します。 this request will select and return all nodes with a tag of amenity=hospital within the bounding box that covers the whole of the England, Wales and Scotland.

Tag Predicates

述語は[key=value]の形式で指定する必要があります。例えば：node[amenity=hospital]は、・・・・

A selection predicate must be of the form [key=value]. For example: node[amenity=hospital] will match any node that has an amenity key with a value of hospital, ie <tag k="amenity" v="hospital"/>.

値を複数指定する為に、演算子を使用する事が出来ます。たとえば、すべての主要道路を選択する： A union operator may be used to select multiple values. For example to select all major roads:

  • way[highway=motorway|motorway_link|trunk|primary]

演算子は、キーにも使用する事が出来ます。例えば、ゴルフコースを選択する： The union operator can also be used with the key. For example to select golf courses:

  • node[amenity|leisure=golf_course]

値にワイルドカードを使う事が出来ます。（キーには使えません。） A wildcard can be used for the value (but not for the key), so predicates similar to the following examples are possible:

  • way[construction=*]
  • way[highway=*]

キーのワイルドカードは、過去にサポートされていましたが、使えなくなります。 Key wildcards were supported in the past, but this is no longer maintained.

Note: URLはUTF - 8のURL以外の場合にはエンコードされたASCII文字が必要です。 The URL needs to be UTF-8 url encoded in case of non-ascii characters.

BBox Predicates

Another form of selection predicate is the bbox pseudo key. A selection predicate of the form [bbox=left,bottom,right,top] defines a bounding box that is used to limit the extent of the result document. Only elements that have some part within the bbox will be included in the result document.

Unlike the standard OSM API, the bbox predicate is not limited in size unless it is used without a tag predicate, in which case it is limited to 100 square degrees.

The default extent, if a bbox predicate is not specified, is the whole planet. This is equivalent to specifying [bbox=-180,-90,180,90].

Child Element Predicates

Items can be selected based on whether or not they have child elements. For example, ways can be selected that do not have any tags or do not have any nodes. This is achieved by using an XPath-like element test. Specifically the following are implemented:

  • /api/0.6/way[nd] - 少なくとも1つのノードを持つウェイを選択する - selects ways that have at least one node
  • /api/0.6/way[tag] - 少なくとも1つのタグがあるウェイを選択する - selects ways that have at least one tag
  • /api/0.6/way[not(nd)] - 任意のノードが存在しないウェイだけを選択する - only selects ways that do not have any nodes
  • /api/0.6/way[not(tag)] - 任意のタグがないウェイだけを選択する - only selects ways that do not have any tags
  • /api/0.6/node[way] - 少なくとも1つのウェイに属しているノードを選択する - selects nodes that belong to at least one way
  • /api/0.6/node[not(way)] - ウェイに属していないノードを選択 - selects nodes that do not belong to any way
  • /api/0.6/node[not(tag)] - 任意のタグがないノードだけを選択する - selects nodes that do not have any tags
  • /api/0.6/relation[node] - 少なくとも1つのノードのメンバーを持つリレーションを選択する - selects relations that have at least one node member
  • /api/0.6/relation[way] - 少なくとも1つのウェイのメンバーを持つリレーションを選択する - selects relations that have at least one way member
  • /api/0.6/relation[relation] - 少なくとも1つのリレーションのメンバーを持つリレーションを選択する - selects relations that have at least one relation member
  • /api/0.6/relation[not(node)] - selects relations that do not have any node members
  • /api/0.6/relation[not(way)] - selects relations that do not have any way members
  • /api/0.6/relation[not(relation)] - selects relations that do not have any relation members

Notes:

  1. If using wget then parenthesis characters need to be escaped, so for negation predicates, use [not\(way\)] rather than [not(way)].
  2. In the OSM xml schema nodes do not really have ways as child elements. However, there is, logically, a many-to-many relationship between nodes and ways, and so xapi implements this relationship and enables nodes to be selected based on whether or not they are members of a way. Of course, the output xml is the same as normal and does not include way elements within a node element.

Escaping

Values within predicates can be escaped by prefixing a backslash character. For example to retrieve elements with a tag value that contains a pipe character such as [route=46|46A] you would need to use [route=46\|46A].

The following characters can be escaped in this way: | [ ] * / =

Spaces in tag values do not normally need to be escaped but this is dependant on the client. In this case you need to use URL escaping which requires that each space be replaced by %20. So [route=46 46A] would become [route=46%2046A].

Tags

The main method of querying Xapi is using a tag/value combination in a predicate. In addition to all the normal tags that you expect to find, Xapi stores a number of pseudo-tags that may be useful. They are all stored in the osm: tag namespace to avoid conflict with other tags.

  • osm:user - when an element has a user attribute this is stored as the pseudo tag osm:user.
  • osm:users - a list of all users who have made edits to an element (edits predating the 0.5 API are not included)
  • osm:timestamp

Usage

Xapi URLs can be used from within any web-browser, however a simple query can return several Mb of data which can overwhelm some browsers. It is recommended that a tool such as wget or curl be used with the output directed to a file. For example, the following command uses wget to select all hospitals and store the result document in a file named data.osm: 

 $ wget http://www.informationfreeway.org/api/0.6/node[amenity=hospital] -O data.osm

Note: If you use curl, it will handle redirections automatically, so you need to query the host server directly or use the "--location" option. Also you need to use the "--globoff" option, otherwise it will try to interpret the brackets ("[", "]") as part of the command line: 

 $ curl --location --globoff http://www.informationfreeway.org/api/0.6/node[amenity=hospital] -o data.osm

If you use a script regularly to fetch data from Xapi it would be helpful to set the user agent string to something meaningful. This will help us understand more about how Xapi is being used.



Limitations

  • Created_by tags. These tags are generally un-interesting and have been suppressed to improve performance.
  • Predicates. Currently each request is limited to one tag predicate and one bbox predicate. In the future it is hoped that more sophisticated conditions will be implemented. Multiple bboxes would be great for applications like GpsMid - they already implemented data retrieval over xapi in Osm2GpsMid for single regions which is very helpful.
  • Request grammar. The request grammar is not formally defined and is not processed using a proper parser, so malformed requests may have unpredictable results. Caveat Emptor.
  • user. The planet.osm dump does not contain user information, but the diff files do. Where available the user attribute is returned for each element. A history of user names is also being built so that an attribution list of all users who have edited an element is provided in the xapi:users tag. This will be complete for all changes since the database was last re-synchronised from a complete planet.osm file. This last happened on March 12, 2008.

See also

Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=JA:Xapi&oldid=1977850"