Class: Rosemary::Api

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/rosemary/api.rb

Overview

The Api class handles all calls to the OpenStreetMap API.

Usage:

require 'rosemary'
auth_client = Rosemary::BasicAuthClient.new(:user_name => 'user', :password => 'a_password')
api = Rosemary::Api.new(auth_client)
@node = api.find_node(1234)
@node.tags << {:wheelchair => 'no'}
@changeset = api.create_changeset('Set the wheelchair tag')
api.save(@node, @changeset)

Constant Summary collapse

API_VERSION =

The OSM API version supported by this gem.

"0.6".freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client = nil) ⇒ Api

Creates an Rosemary::Api object with an optional client

Parameters:

  • client (Rosemary::Client) (defaults to: nil) —

    the client to authenticate the user for write access.



40
41
42
 
# File 'lib/rosemary/api.rb', line 40

def initialize(client=nil)
  @client = client
end

Instance Attribute Details

#changeset ⇒ Rosemary::Changeset

Returns the current changeset to be used for all writing acces.

Returns:



36
37
38
 
# File 'lib/rosemary/api.rb', line 36

def changeset
  @changeset
end

#client ⇒ Rosemary::Client

Returns the client to be used to authenticate the user towards the OSM API.

Returns:

  • (Rosemary::Client) —

    the client to be used to authenticate the user towards the OSM API.



33
34
35
 
# File 'lib/rosemary/api.rb', line 33

def client
  @client
end

Instance Method Details

#close_changeset(changeset) ⇒ Object

Closes the given changeset.

Parameters:



184
185
186
 
# File 'lib/rosemary/api.rb', line 184

def close_changeset(changeset)
  put("/changeset/#{changeset.id}/close")
end

#create(element, changeset) ⇒ Fixnum

Create a new element using API write access.

Parameters:

Returns:

  • (Fixnum) —

    the id of the newly created element.



145
146
147
148
 
# File 'lib/rosemary/api.rb', line 145

def create(element, changeset)
  element.changeset = changeset.id
  put("/#{element.type.downcase}/create", :body => element.to_xml)
end

#create_changeset(comment = nil, tags = {}) ⇒ Rosemary::Changeset

Create a new changeset with an optional comment

Parameters:

  • comment (String) (defaults to: nil) —

    a meaningful comment for this changeset

Returns:

Raises:



166
167
168
169
170
171
 
# File 'lib/rosemary/api.rb', line 166

def create_changeset(comment = nil, tags = {})
  tags.merge!(:comment => comment) { |key, v1, v2| v1 }
  changeset = Changeset.new(:tags => tags)
  changeset_id = put("/changeset/create", :body => changeset.to_xml).to_i
  find_changeset(changeset_id) unless changeset_id == 0
end

#create_note(note) ⇒ Object

Create a note

call-seq: create_note(lat: 51.00, lon: 0.1, text: ‘Test note’) -> Rosemary::Note



213
214
215
 
# File 'lib/rosemary/api.rb', line 213

def create_note(note)
  post("/notes", :query => note)
end

#destroy(element, changeset) ⇒ Fixnum

Deletes the given element using API write access.

Parameters:

Returns:

  • (Fixnum) —

    the new version of the deleted element.



122
123
124
125
126
 
# File 'lib/rosemary/api.rb', line 122

def destroy(element, changeset)
  element.changeset = changeset.id
  response = delete("/#{element.type.downcase}/#{element.id}", :body => element.to_xml) unless element.id.nil?
  response.to_i # New version number
end

#find_bounding_box(left, bottom, right, top) ⇒ Rosemary::BoundingBox

Get the bounding box which is represented by the Rosemary::BoundingBox

Parameters:

  • left (Numeric) —

    is the longitude of the left (westernmost) side of the bounding box.

  • bottom (Numeric) —

    is the latitude of the bottom (southernmost) side of the bounding box.

  • right (Numeric) —

    is the longitude of the right (easternmost) side of the bounding box.

  • top (Numeric) —

    is the latitude of the top (northernmost) side of the bounding box.

Returns:

  • (Rosemary::BoundingBox) —

    the bounding box containing all ways, nodes and relations inside the given coordinates



104
105
106
 
# File 'lib/rosemary/api.rb', line 104

def find_bounding_box(left,bottom,right,top)
  do_request(:get, "/map?bbox=#{left},#{bottom},#{right},#{top}", {} )
end

#find_changeset(id) ⇒ Rosemary::Changeset

Get a Changeset with specified ID from API.

Parameters:

  • id (Integer) —

    the ID for the changeset you look for

Returns:



177
178
179
 
# File 'lib/rosemary/api.rb', line 177

def find_changeset(id)
  find_element('changeset', id)
end

#find_changesets_for_user(options = {}) ⇒ Object 



188
189
190
191
192
 
# File 'lib/rosemary/api.rb', line 188

def find_changesets_for_user(options = {})
  user_id = find_user.id
  changesets = get("/changesets", :query => options.merge({:user => user_id}))
  changesets.nil? ? [] : changesets
end

#find_element(type, id) ⇒ Object

Get an object (‘node’, ‘way’, or ‘relation’) with specified ID from API.

call-seq: find_element(‘node’, id) -> Rosemary::Element

Raises:

  • (ArgumentError) 


198
199
200
201
202
203
204
205
206
207
 
# File 'lib/rosemary/api.rb', line 198

def find_element(type, id)
  raise ArgumentError.new("type needs to be one of 'node', 'way', and 'relation'") unless type =~ /^(node|way|relation|changeset)$/
  return nil if id.nil?
  begin
    response = get("/#{type}/#{id}")
    response.is_a?(Array ) ? response.first : response
  rescue NotFound
    nil
  end
end

#find_node(id) ⇒ Rosemary::Node

Get a Node with specified ID from API.

Parameters:

  • id (Fixnum) —

    the id of the node to find.

Returns:

Raises:



49
50
51
 
# File 'lib/rosemary/api.rb', line 49

def find_node(id)
  find_element('node', id)
end

#find_open_changeset(id) ⇒ Object 



80
81
82
83
 
# File 'lib/rosemary/api.rb', line 80

def find_open_changeset(id)
  cs = find_changeset(id)
  (cs && cs.open?) ? cs : nil
end

#find_or_create_open_changeset(id, comment = nil, tags = {}) ⇒ Object

Get a Changeset with specified ID from API if that changeset is missing, id is nil, or the changeset is closed create a new one

call-seq: find_or_create_open_changeset(id, comment) -> Rosemary::Changeset



76
77
78
 
# File 'lib/rosemary/api.rb', line 76

def find_or_create_open_changeset(id, comment = nil, tags = {})
  find_open_changeset(id) || create_changeset(comment, tags)
end

#find_relation(id) ⇒ Object

Get a Relation with specified ID from API.

call-seq: find_relation(id) -> Rosemary::Relation



66
67
68
 
# File 'lib/rosemary/api.rb', line 66

def find_relation(id)
  find_element('relation', id)
end

#find_user ⇒ Object

Get the user which represented by the Rosemary::Client

@return: [Rosemary::User] user the user authenticated using the current client

Raises:



89
90
91
92
93
94
 
# File 'lib/rosemary/api.rb', line 89

def find_user
  raise CredentialsMissing if client.nil?
  resp = do_authenticated_request(:get, "/user/details")
  raise resp if resp.is_a? String
  resp
end

#find_way(id) ⇒ Rosemary::Way

Get a Way with specified ID from API.

Parameters:

  • id (Fixnum) —

    the id of the node to find.

Returns:



58
59
60
 
# File 'lib/rosemary/api.rb', line 58

def find_way(id)
  find_element('way', id)
end

#permissions ⇒ Object 



109
110
111
112
113
114
115
 
# File 'lib/rosemary/api.rb', line 109

def permissions
  if client.nil?
    get("/permissions")
  else
    do_authenticated_request(:get, "/permissions")
  end
end

#save(element, changeset) ⇒ Object

Creates or updates an element depending on the current state of persistance.

Parameters:



132
133
134
135
136
137
138
 
# File 'lib/rosemary/api.rb', line 132

def save(element, changeset)
  response = if element.id.nil?
    create(element, changeset)
  else
    update(element, changeset)
  end
end

#update(element, changeset) ⇒ Fixnum

Update an existing element using API write access.

Parameters:

Returns:

  • (Fixnum) —

    the versiom of the updated element.



155
156
157
158
159
 
# File 'lib/rosemary/api.rb', line 155

def update(element, changeset)
  element.changeset = changeset.id
  response = put("/#{element.type.downcase}/#{element.id}", :body => element.to_xml)
  response.to_i # New Version number
end