epok 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12d0e1ef79e2fd5ff522e79748f413cdb123a79c863bba24a85dce868a1c7127
-  data.tar.gz: 0c44daa4fe8d10908c75301d9a363bacf4d03ff0edf0eb13a2ff307cf96fe286
+  metadata.gz: ee8d9d659f3f1da4d0e290c2fe57173ca577ccaf6ae8c9ab5d6fb0df5a41045d
+  data.tar.gz: d075af0af60603bfc513f65f26f6656cc9a43e3e3a6dd25da47245cd96a0ea05
 SHA512:
-  metadata.gz: 8358374a58c28bd2cb5f10ec9ce94248b0a9ba2a2bb2a733f4cfb003a62fecf90e8e6ec46ffd8648b8ab4172df745976586fcc09b264d10c26f34438138af961
-  data.tar.gz: bcc962b28eaf4a3d8bb62325a422709488a437338aad6c7eced0afe9bce2c27a5865f7d367674759888e7fe78c28f46d8fb4350b3424dab60fba894627050816
+  metadata.gz: d57ad60dcd6be25dcd1ad82039809fccc8d9039ed31439e3209fd2c85cdbe82cccf83a9e9c9846989f182c9290ccd60d440a69d3aa673f500f160cd31cf55ee2
+  data.tar.gz: 7b850241d36d95455e480cb26222233927447bab1cffe547388a53c5d0c92c6d61ae387c3c70db9aae7eb784623c38a5bf220f693f6fde06fc39a10cd01c83fb

data/CLAUDE.md

@@ -14,18 +14,34 @@ bundle exec swarf lib/    # complexity vs. coverage report, worst first
 Cassettes are gitignored, so the first test run hits the live API.
 The API rejects curl's default User-Agent, but Ruby's Net::HTTP works fine.
 
-## Releasing
-
-1. Make sure `main` is clean and pushed, and `bundle exec rake test` passes.
-2. Bump `Epok::VERSION` in `lib/epok/version.rb`. Follow semver:
-   patch for fixes, minor for new behaviour, major for breaking changes.
-3. Commit it as `Bump version to X.Y.Z`.
-4. Run `bundle exec rake release`. This builds the gem, creates and pushes
-   the `vX.Y.Z` tag, and pushes the gem to rubygems.org. It needs rubygems
-   credentials (`gem signin`) and may prompt for an OTP if the account has
-   MFA enabled. If it prompts, the user has to run it themselves.
-5. Create a GitHub release from the tag with a short summary of what changed:
-   `gh release create vX.Y.Z --generate-notes`.
-
-Version numbers on rubygems.org cannot be reused, so check the diff before
-running step 4.
+## API notes
+
+Official docs are Swagger specs on the city's 3scale portal. The HTML at
+https://datosabiertos-apis.buenosaires.gob.ar/BA_Root/Documentacion is
+JavaScript-rendered; fetch the JSON directly:
+
+- Index: https://datosabiertos-apis.buenosaires.gob.ar/api_docs/services.json
+- EPOk ("Busquedas de Lugares"): .../api_docs/services/10.json
+- USIG Geocoder: .../api_docs/services/8.json
+- Datos Útiles: .../api_docs/services/9.json
+
+The specs list `datosabiertos-*-apis.buenosaires.gob.ar` hosts that return
+404. The live hosts are `epok.buenosaires.gob.ar` for EPOk and
+`ws.usig.buenosaires.gob.ar` for USIG (REST index with docs at
+https://ws.usig.buenosaires.gob.ar/rest/).
+
+- `/buscar/` also takes `categoria` (comma-separated), `clase`, `bbox`,
+  `start`, `limit` and `totalFull`.
+- `/reverseGeocoderLugares/` takes `srid` (default 4326) and `radio`
+  (default 1 metre, hence our 500 default).
+- Unknown ids return `200 {}`, unknown categories return an empty list.
+- Object coordinates are projected (Gauss-Krüger Buenos Aires). USIG's
+  `/rest/convertir_coordenadas` turns them into longitude and latitude.
+- `ws.usig.buenosaires.gob.ar/datos_utiles?x=&y=` answers with empty strings
+  outside the city; `Epok.datos_utiles` turns those into nil.
+- `servicios.usig.buenosaires.gob.ar/normalizar/?direccion=&geocodificar=true`
+  matches across the whole AMBA, CABA first. Coordinates come back as
+  strings for CABA and floats elsewhere. No match is `200` with an empty
+  list and an `errorMessage`; `Epok.geocode` raises NotFound with it.
+- A December 2025 city report says "API USIG" is being replaced by
+  "API Servicios Geo" during 2026. The USIG hosts above may move.

data/Gemfile

@@ -4,4 +4,5 @@ git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 gemspec
 
+gem "irb", group: :development
 gem "swarf", group: :development

data/Gemfile.lock

@@ -1,31 +1,47 @@
 PATH
   remote: .
   specs:
-    epok (0.2.0)
+    epok (0.5.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
-    ansi (1.6.0)
     bigdecimal (4.1.3)
-    builder (3.3.0)
     crack (1.0.1)
       bigdecimal
       rexml
+    erb (6.0.7)
     hashdiff (1.2.1)
+    io-console (0.9.3)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    logger (1.7.0)
     minitest (5.27.0)
-    minitest-reporters (1.8.0)
-      ansi
-      builder
-      minitest (>= 5.0, < 7)
-      ruby-progressbar
+    pp (0.6.4)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
     public_suffix (7.0.5)
     rake (13.4.2)
+    rbs (4.2.0)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    rdoc (8.0.0)
+      erb
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
+      tsort
+    reline (0.7.0)
+      io-console (~> 0.5)
     rexml (3.4.4)
-    ruby-progressbar (1.13.0)
     swarf (0.2.0)
+    tsort (0.2.0)
     vcr (6.4.0)
     webmock (3.26.4)
       addressable (>= 2.8.0)
@@ -38,8 +54,8 @@ PLATFORMS
 
 DEPENDENCIES
   epok!
+  irb
   minitest (~> 5.0)
-  minitest-reporters (~> 1.3, >= 1.3.6)
   rake (~> 13.0)
   swarf
   vcr (~> 6.0)
@@ -47,19 +63,26 @@ DEPENDENCIES
 
 CHECKSUMS
   addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af
-  ansi (1.6.0) sha256=ac9ea0c0ea8d32fb4e271348e609963ac78882f34b73836c2a02b3622e666658
   bigdecimal (4.1.3) sha256=61ebe1e5e559bdc3cc6f2c0ee7f427321fc838f59611c294356eb04d6e21cf66
-  builder (3.3.0) sha256=497918d2f9dca528fdca4b88d84e4ef4387256d984b8154e9d5d3fe5a9c8835f
   crack (1.0.1) sha256=ff4a10390cd31d66440b7524eb1841874db86201d5b70032028553130b6d4c7e
-  epok (0.2.0)
+  epok (0.5.0)
+  erb (6.0.7) sha256=c5ca6dc25b0ef974a44dc8f59fe847577122483b1968a38dec305c60bf91ee92
   hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
+  io-console (0.9.3) sha256=f555049461b0afb78a5448b5be8e7c7b48371347cd48abfc22814764160000dd
+  irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   minitest (5.27.0) sha256=2d3b17f8a36fe7801c1adcffdbc38233b938eb0b4966e97a6739055a45fa77d5
-  minitest-reporters (1.8.0) sha256=8ce5280fb73ad3178ae525454df169b6f28c1b38b1d088ea91815d3a370ba384
+  pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
+  prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
   public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
   rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+  rbs (4.2.0) sha256=51f7b886dcc05bc09e10b901daa6a81829f6adc03101d6ca9ea4aac6103e0674
+  rdoc (8.0.0) sha256=03bf8c08a9639658855a0cfd77c0abca8325c227693f7f33f82957811348c469
+  reline (0.7.0) sha256=5b012d8e55dbf9d450f12bde2cf7d15ff546ae80b3f8f3b30e570d431815583d
   rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
-  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
   swarf (0.2.0) sha256=b4306a244fe4b096cfe263e452e666156856eac2467ae5d770639ef11388b375
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
   vcr (6.4.0) sha256=077ac92cc16efc5904eb90492a18153b5e6ca5398046d8a249a7c96a9ea24ae6
   webmock (3.26.4) sha256=8d8da206d217ebe6968cfb09c77f4533c23074e1432bad865f3994eacbaad50d
 

data/README.md

@@ -20,29 +20,73 @@ Or install it yourself as:
 
 ## Usage
 
+"I'm at Callao y Corrientes, what's around me?" in five requests:
+
 ```ruby
->> obelisco = Epok::Location.new(x: -58.381570, y: -34.603738)
-=> #<struct Epok::Location x=-58.38157, y=-34.603738>
+require "epok"
+
+# 1. Turn a typed address into coordinates.
+here = Epok.geocode("callao y corrientes").first
+puts "You are at #{here.address}"
+
+# 2. Which neighbourhood and comuna is that?
+area = Epok.datos_utiles(here.location)
+puts "That's #{area.barrio}, #{area.comuna}"
+
+# 3. What's within 300 metres, by category?
+nearby = Epok.geocoder(here.location, %w[estaciones_de_subte farmacias], radius: 300)
+nearby.sort_by(&:distance).first(5).each do |place|
+  puts "  #{place.distance.round} m  #{place.name} (#{place.kind})"
+end
+
+# 4. Drill into one: full record and coordinates for a map pin.
+closest = nearby.min_by(&:distance)
+puts "Pin: #{closest.location.y}, #{closest.location.x}"
+closest.content.each { |key, value| puts "  #{key}: #{value}" }
+```
+
+```
+You are at CALLAO AV. y CORRIENTES AV., CABA
+That's San Nicolas, Comuna 3
+  3 m  CALLAO - MAESTRO ALFREDO BRAVO (Línea B) (Estación de Subte (Metro))
+  42 m  Farmacia en CORRIENTES AV. 1820 (Farmacia)
+  73 m  Farmacia en CORRIENTES AV. 1835 (Farmacia)
+  98 m  Farmacia en CALLAO AV. 477 (Farmacia)
+  111 m  Farmacia en CORRIENTES AV. 1880 (Farmacia)
+Pin: -34.604419, -58.392318
+  Nombre: CALLAO - MAESTRO ALFREDO BRAVO (Línea B)
+  Línea: B
+  Estado: Estación Malabia cerrada por obras de renovación integral.
+  Cabeceras: J. M. de Rosas - L. N. Alem
+  Tiempo: 27 min.
+```
 
->> pharmacies_around_obelisco = Epok.geocoder(obelisco, "farmacias")
-=> #<Epok::Geocoder:0x00007f8719ab4f08 @x=-58.38157, @y=-34.603738, @categories="farmacias">
+Steps 1 to 3 are one request each; step 4 is two (the record, then the coordinate conversion). The content hash is whatever the city publishes for that category: subway stations carry line, status and travel time, pharmacies carry phone and delivery details.
 
->> pharmacies_around_obelisco.first.content
-=> {"Nombre"=>"Farmacia en PELLEGRINI, CARLOS 765", "Teléfono"=>"43223198 43220298"}
+### The rest
 
->> cgp = Epok.search("cgp")
-=> #<Epok::Search:0x00007f871a09ac60 @query="cgp">
+**Search by text**, optionally filtered by category and capped:
 
->> sede_4 = cgp.first
-=> #<Epok::Object:0x00007f8719b36788 @id="sedes_de_comunas|4">
+```ruby
+Epok.search("cgp", categories: "sedes_de_comunas", limit: 3).map(&:name)
+# => ["Sede Comunal 4", "Sede Comunal 9", "Sede Comunal 10"]
+```
 
->> sede_4.name
-=> "Sede Comunal 4"
+**Categories** are what the geocoder and the search filter take. There are 167, each with an id, a display name and a description:
 
->> sede_4.content
-=> {"Nombre"=>"Sede Comunal 4", "Dirección"=>"BARCO CENTENERA del 2906", "Teléfonos"=>"4918-2243/1815/8920-4949 9024 Int. 105", "Trámites y Servicios"=>"<a href=\"http://www.buenosaires.gob.ar/comuna-4/sede-comunal-4\" target=\"_blank\">link</a>"}
+```ruby
+Epok.categories.find { |c| c.id == "farmacias" }
+# => #<struct Epok::Category id="farmacias", name="Farmacias", description="">
 ```
 
+**Collections** from `search` and `geocoder` are `Enumerable` and lazy: nothing is requested until you iterate.
+
+**Objects** know their `id`, `name`, `kind`, `category` and, from the geocoder, `distance` in metres straight from the listing. `content`, `normalized_address` and `location` fetch the full record on first use; `location` also converts the city's projected coordinates through USIG. `Epok::Object.new("farmacias|1082")` looks one up by id.
+
+**Locations** are `Epok::Location.new(x: longitude, y: latitude)`. `geocode` returns every match across the metro area, city first, as `Address` structs with `address`, `partido`, `localidad` and `location`. `datos_utiles` returns nil for the city fields outside CABA and fills `partido_amba` and `localidad_amba` instead.
+
+**Errors**: every request failure raises `Epok::Error`. An unknown id or address raises `Epok::NotFound`.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/bin/console

@@ -4,6 +4,4 @@ require "bundler/setup"
 require "epok"
 require "irb"
 
-@obelisco = Epok::Location.new(x: -58.381570, y: -34.603738)
-
 IRB.start(__FILE__)

data/epok.gemspec

@@ -18,7 +18,6 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "minitest-reporters", "~> 1.3", ">= 1.3.6"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "vcr", "~> 6.0"
   spec.add_development_dependency "webmock", "~> 3.5", ">= 3.5.1"

data/lib/epok/api.rb

@@ -2,25 +2,74 @@ require "net/http"
 require "json"
 
 module Epok
+  class Error < StandardError; end
+  class NotFound < Error; end
+
   class API
-    BASE_URL = "https://epok.buenosaires.gob.ar".freeze
+    EPOK_URL = "https://epok.buenosaires.gob.ar".freeze
+    USIG_URL = "https://ws.usig.buenosaires.gob.ar".freeze
+    USIG_SERVICES_URL = "https://servicios.usig.buenosaires.gob.ar".freeze
+    TIMEOUT = 10
 
     def self.object(id)
-      JSON.parse(get("/getObjectContent/?id=#{id}"))
+      object = get(EPOK_URL, "/getObjectContent/", id: id)
+      raise NotFound, "no object with id #{id}" if object.empty?
+
+      object
+    end
+
+    def self.search(query, categories = nil, limit = nil)
+      params = { texto: query, categoria: categories, limit: limit }.compact
+
+      get(EPOK_URL, "/buscar/", params)["instancias"]
+    end
+
+    def self.geocoder(x, y, categories, radius)
+      get(EPOK_URL, "/reverseGeocoderLugares/",
+        x: x, y: y, categorias: categories, radio: radius)["instancias"]
+    end
+
+    def self.categories
+      get(EPOK_URL, "/getCategorias/", {})["categorias"]
+    end
+
+    def self.geocode(text)
+      response = get(USIG_SERVICES_URL, "/normalizar/", direccion: text, geocodificar: true)
+      addresses = response["direccionesNormalizadas"]
+      raise NotFound, response["errorMessage"] if addresses.empty?
+
+      addresses
     end
 
-    def self.search(query)
-      JSON.parse(get("/buscar/?texto=#{query}"))["instancias"]
+    def self.datos_utiles(x, y)
+      get(USIG_URL, "/datos_utiles", x: x, y: y)
     end
 
-    def self.geocoder(x, y, categories)
-      JSON.parse(get(
-        "/reverseGeocoderLugares/?x=#{x}&y=#{y}&categorias=#{categories}&radio=500"
-      ))["instancias"]
+    # Converts EPOk's projected coordinates (Gauss-Krüger Buenos Aires) to
+    # longitude and latitude through the city's USIG service.
+    def self.to_lonlat(x, y)
+      response = get(USIG_URL, "/rest/convertir_coordenadas", x: x, y: y, output: "lonlat")
+      raise Error, "USIG could not convert (#{x}, #{y})" unless response["tipo_resultado"] == "Ok"
+
+      response["resultado"].values_at("x", "y").map(&:to_f)
     end
 
-    def self.get(path)
-      Net::HTTP.get_response(URI("#{BASE_URL}#{path}")).body
+    def self.get(host, path, params)
+      uri = URI("#{host}#{path}")
+      uri.query = URI.encode_www_form(params)
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: true,
+        open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
+        http.get(uri.request_uri)
+      end
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise Error, "EPOk responded #{response.code} to #{uri}"
+      end
+
+      JSON.parse(response.body)
+    rescue SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError, JSON::ParserError => e
+      raise Error, "#{e.class}: #{e.message}"
     end
     private_class_method :get
   end

data/lib/epok/collection.rb

@@ -2,22 +2,18 @@ module Epok
   class Collection
     include Enumerable
 
-    attr_reader :data
-
-    def initialize(data, id = "id")
-      @data = collection(data, id)
+    def initialize(&fetch)
+      @fetch = fetch
     end
 
     def each(&block)
-      data.each(&block)
+      objects.each(&block)
     end
 
     private
 
-    def collection(data, id)
-      data.map do |item|
-        Object.new(item[id])
-      end
+    def objects
+      @objects ||= @fetch.call.map { |item| Object.new(item) }
     end
   end
 end

data/lib/epok/object.rb

@@ -1,19 +1,48 @@
 module Epok
   class Object
-    attr_reader :id
+    attr_reader :id, :distance
 
-    def initialize(id)
-      @id = id
+    # Accepts either an id ("farmacias|1082") or a result hash from a search
+    # or geocoder listing. Listing attributes are available immediately; the
+    # full content is fetched on first use.
+    def initialize(attributes)
+      attributes = { "id" => attributes } if attributes.is_a?(String)
+
+      @id = attributes.fetch("id")
+      @name = attributes["nombre"]&.strip
+      @kind = attributes["clase"]
+      @distance = attributes["distancia"]&.to_f
     end
 
     def name
-      content["Nombre"]
+      @name ||= content["Nombre"]
+    end
+
+    def kind
+      @kind ||= object["clase"]
+    end
+
+    def category
+      id.split("|").first
     end
 
     def normalized_address
       object["direccionNormalizada"]
     end
 
+    # Longitude and latitude as a Location, or nil when EPOk has no
+    # centroid for the object. Costs one extra request the first time.
+    def location
+      return @location if defined?(@location)
+
+      centroid = object.dig("ubicacion", "centroide")
+      @location = centroid && begin
+        x, y = centroid[/\(([^)]*)\)/, 1].split.map(&:to_f)
+        lon, lat = API.to_lonlat(x, y)
+        Location.new(x: lon, y: lat)
+      end
+    end
+
     def content
       object["contenido"].each_with_object({}) do |entry, hash|
         name, value = entry.values_at("nombre", "valor")

data/lib/epok/version.rb

@@ -1,3 +1,3 @@
 module Epok
-  VERSION = "0.2.0"
+  VERSION = "0.5.0"
 end

data/lib/epok.rb

@@ -1,17 +1,65 @@
 require "epok/api"
-require "epok/collectable"
 require "epok/collection"
-require "epok/geocoder"
 require "epok/object"
-require "epok/search"
 require "epok/version"
 
 module Epok
-  def self.search(query)
-    Search.new(query)
+  Location = Struct.new(:x, :y, keyword_init: true)
+  Category = Struct.new(:id, :name, :description, keyword_init: true)
+  DatosUtiles = Struct.new(
+    :barrio, :comuna, :comisaria, :comisaria_vecinal,
+    :area_hospitalaria, :region_sanitaria, :distrito_escolar,
+    :partido_amba, :localidad_amba,
+    keyword_init: true
+  )
+
+  Address = Struct.new(:address, :partido, :localidad, :location, keyword_init: true)
+
+  DEFAULT_RADIUS = 500
+
+  def self.search(query, categories: nil, limit: nil)
+    categories = Array(categories).join(",") if categories
+
+    Collection.new { API.search(query, categories, limit) }
+  end
+
+  def self.geocoder(location, categories, radius: DEFAULT_RADIUS)
+    categories = Array(categories).join(",")
+
+    Collection.new { API.geocoder(location.x, location.y, categories, radius) }
+  end
+
+  def self.geocode(text)
+    API.geocode(text).map do |address|
+      x, y = address["coordenadas"].values_at("x", "y").map(&:to_f)
+
+      Address.new(
+        address: address["direccion"],
+        partido: address["nombre_partido"],
+        localidad: address["nombre_localidad"],
+        location: Location.new(x: x, y: y)
+      )
+    end
+  end
+
+  def self.datos_utiles(location)
+    datos = API.datos_utiles(location.x, location.y)
+
+    DatosUtiles.new(
+      DatosUtiles.members.to_h do |member|
+        value = datos[member.to_s].to_s.strip.squeeze(" ")
+        [member, value.empty? ? nil : value]
+      end
+    )
   end
 
-  def self.geocoder(location, categories)
-    Geocoder.new(location, categories)
+  def self.categories
+    API.categories.map do |category|
+      Category.new(
+        id: category["nombre_normalizado"],
+        name: category["nombre"],
+        description: category["descripcion"]
+      )
+    end
   end
 end

data/test/epok/api_test.rb

@@ -0,0 +1,65 @@
+require "test_helper"
+
+module Epok
+  class APITest < Minitest::Test
+    include WebMock::API
+
+    def setup
+      VCR.eject_cassette
+      VCR.turn_off!
+    end
+
+    def teardown
+      WebMock.reset!
+      VCR.turn_on!
+    end
+
+    def test_that_a_server_error_raises
+      stub_request(:get, /epok/).to_return(status: 500, body: "boom")
+
+      error = assert_raises(Error) { Epok.search("x").first }
+      assert_match "500", error.message
+    end
+
+    def test_that_a_timeout_raises
+      stub_request(:get, /epok/).to_timeout
+
+      assert_raises(Error) { Epok.categories }
+    end
+
+    def test_that_a_non_json_body_raises
+      stub_request(:get, /epok/).to_return(status: 200, body: "<html>")
+
+      assert_raises(Error) { Epok.search("x").first }
+    end
+
+    def test_that_a_missing_object_raises_not_found
+      stub_request(:get, /getObjectContent/).to_return(status: 200, body: "{}")
+
+      assert_raises(NotFound) { Object.new("nope|1").content }
+    end
+
+    def test_that_an_object_without_a_centroid_has_no_location
+      stub_request(:get, /getObjectContent/)
+        .to_return(status: 200, body: '{"contenido": [], "ubicacion": null}')
+
+      object = Object.new("espacios_verdes_publicos|1")
+
+      assert_nil object.location
+      assert_nil object.location
+    end
+
+    def test_that_a_failed_coordinate_conversion_raises
+      stub_request(:get, /getObjectContent/)
+        .to_return(status: 200, body: '{"ubicacion": {"centroide": "POINT (1 2)"}}')
+      stub_request(:get, /usig/)
+        .to_return(status: 200, body: '{"tipo_resultado":"Error","resultado":{"x":"","y":""}}')
+
+      assert_raises(Error) { Object.new("x|1").location }
+    end
+
+    def test_that_not_found_is_an_error
+      assert_operator NotFound, :<, Error
+    end
+  end
+end

data/test/epok/categories_test.rb

@@ -0,0 +1,26 @@
+require "test_helper"
+
+module Epok
+  class CategoriesTest < Minitest::Test
+    def setup
+      VCR.insert_cassette("categories")
+    end
+
+    def teardown
+      VCR.eject_cassette("categories")
+    end
+
+    def test_that_categories_are_listed
+      categories = Epok.categories
+
+      assert_operator categories.size, :>, 100
+      assert categories.all? { |category| category.is_a?(Category) }
+    end
+
+    def test_that_a_category_has_an_id_and_a_name
+      pharmacies = Epok.categories.find { |category| category.id == "farmacias" }
+
+      assert_equal "Farmacias", pharmacies.name
+    end
+  end
+end

data/test/epok/collection_test.rb

@@ -0,0 +1,22 @@
+require "test_helper"
+
+module Epok
+  class CollectionTest < Minitest::Test
+    def test_that_a_collection_is_enumerable
+      collection = Collection.new { [{"id" => "a|1"}, {"id" => "a|2"}] }
+
+      assert_equal ["a|1", "a|2"], collection.map(&:id)
+      assert_equal 2, collection.count
+    end
+
+    def test_that_a_collection_fetches_lazily_and_once
+      calls = 0
+      collection = Collection.new { calls += 1; [{"id" => "a|1"}] }
+
+      assert_equal 0, calls
+      collection.first
+      collection.to_a
+      assert_equal 1, calls
+    end
+  end
+end

data/test/epok/datos_utiles_test.rb

@@ -0,0 +1,39 @@
+require "test_helper"
+
+module Epok
+  class DatosUtilesTest < Minitest::Test
+    def setup
+      VCR.insert_cassette("datos_utiles")
+    end
+
+    def teardown
+      VCR.eject_cassette("datos_utiles")
+    end
+
+    def test_that_datos_utiles_returns_the_barrio_and_comuna
+      datos = Epok.datos_utiles(Location.new(x: -58.381570, y: -34.603738))
+
+      assert_equal "San Nicolas", datos.barrio
+      assert_equal "Comuna 1", datos.comuna
+    end
+
+    def test_that_datos_utiles_returns_the_other_jurisdictions
+      datos = Epok.datos_utiles(Location.new(x: -58.381570, y: -34.603738))
+
+      assert_equal "3", datos.comisaria
+      assert_equal "1B", datos.comisaria_vecinal
+      assert_equal "HTAL. DR. J.M. RAMOS MEJÍA", datos.area_hospitalaria
+      assert_equal "I (Este)", datos.region_sanitaria
+      assert_equal "Distrito Escolar I", datos.distrito_escolar
+    end
+
+    def test_that_outside_the_city_fields_are_nil_and_amba_is_filled
+      datos = Epok.datos_utiles(Location.new(x: -58.60, y: -34.60))
+
+      assert_nil datos.barrio
+      assert_nil datos.comuna
+      assert_equal "Tres de Febrero", datos.partido_amba
+      assert_equal "Ciudad Jardín Lomas de El Palomar", datos.localidad_amba
+    end
+  end
+end

data/test/epok/geocode_test.rb

@@ -0,0 +1,36 @@
+require "test_helper"
+
+module Epok
+  class GeocodeTest < Minitest::Test
+    def setup
+      VCR.insert_cassette("geocode")
+    end
+
+    def teardown
+      VCR.eject_cassette("geocode")
+    end
+
+    def test_that_an_address_is_normalized_and_located
+      address = Epok.geocode("cabildo 1234").first
+
+      assert_equal "CABILDO AV. 1234, CABA", address.address
+      assert_in_delta(-58.448466, address.location.x)
+      assert_in_delta(-34.568290, address.location.y)
+    end
+
+    def test_that_an_address_has_a_partido_and_localidad
+      addresses = Epok.geocode("cabildo 1234")
+
+      assert_equal "CABA", addresses.first.partido
+      assert_equal "CABA", addresses.first.localidad
+      assert_equal "La Matanza", addresses[1].partido
+      assert_equal "Villa Madero", addresses[1].localidad
+    end
+
+    def test_that_an_unknown_address_raises_not_found
+      error = assert_raises(NotFound) { Epok.geocode("xyzzy 999") }
+
+      assert_equal "Calle inexistente: xyzzy 999", error.message
+    end
+  end
+end

data/test/epok/geocoder_test.rb

@@ -3,7 +3,7 @@ require "test_helper"
 module Epok
   class GeocoderTest < Minitest::Test
     def setup
-      VCR.insert_cassette("geocoder", record: :new_episodes)
+      VCR.insert_cassette("geocoder")
     end
 
     def teardown
@@ -18,12 +18,32 @@ module Epok
       assert_match "Línea D", result.name
     end
 
+    def test_that_geocoder_results_have_a_distance
+      assert_operator result.distance, :<, 500
+    end
+
+    def test_that_geocoder_accepts_a_radius
+      near = Epok.geocoder(obelisco, "estaciones_de_subte", radius: 100)
+      far = Epok.geocoder(obelisco, "estaciones_de_subte", radius: 1000)
+
+      assert_operator near.count, :<, far.count
+      assert near.all? { |station| station.distance <= 100 }
+    end
+
+    def test_that_geocoder_accepts_several_categories
+      results = Epok.geocoder(obelisco, %w[estaciones_de_subte farmacias])
+
+      assert_equal %w[estaciones_de_subte farmacias].sort, results.map(&:category).uniq.sort
+    end
+
     private
 
     def result
-      obelisco = Location.new(x: -58.381570, y: -34.603738)
-      results = Geocoder.new(obelisco, "estaciones_de_subte")
-      results.first
+      Epok.geocoder(obelisco, "estaciones_de_subte").first
+    end
+
+    def obelisco
+      Location.new(x: -58.381570, y: -34.603738)
     end
   end
 end

data/test/epok/object_test.rb

@@ -14,10 +14,26 @@ module Epok
       assert_equal "BIBLIOTECA ANMAT", object.name
     end
 
+    def test_that_an_object_has_a_kind
+      assert_equal "Dependencias Culturales", object.kind
+    end
+
+    def test_that_an_object_has_a_category
+      assert_equal "dependencias_culturales", object.category
+    end
+
     def test_that_an_object_has_a_normalized_address
       assert_equal "DE MAYO AV. 869", object.normalized_address
     end
 
+    def test_that_an_object_has_a_location
+      location = object.location
+
+      assert_instance_of Location, location
+      assert_in_delta(-58.38, location.x, 0.01)
+      assert_in_delta(-34.61, location.y, 0.01)
+    end
+
     def test_that_an_object_has_content
       expected_content = {
         "Nombre" => "BIBLIOTECA ANMAT",
@@ -36,6 +52,27 @@ module Epok
       assert_equal expected_content, object.content
     end
 
+    def test_that_listing_attributes_do_not_fetch
+      object = Object.new(
+        "id" => "farmacias|1082",
+        "nombre" => "Farmacia en CERRITO 342 ",
+        "clase" => "Farmacia",
+        "distancia" => "112.31"
+      )
+
+      VCR.eject_cassette
+      VCR.turned_off do
+        assert_equal "Farmacia en CERRITO 342", object.name
+        assert_equal "Farmacia", object.kind
+        assert_equal "farmacias", object.category
+        assert_in_delta 112.31, object.distance
+      end
+    end
+
+    def test_that_an_object_built_from_an_id_has_no_distance
+      assert_nil object.distance
+    end
+
     private
 
     def object

data/test/epok/search_test.rb

@@ -18,11 +18,30 @@ module Epok
       assert_match "San Miguel de Garicoits", result.name
     end
 
+    def test_that_search_encodes_the_query
+      assert_match "Peña", Epok.search("plaza peña").first.name
+    end
+
+    def test_that_search_filters_by_category
+      results = Epok.search("san martin", categories: "estaciones_de_subte")
+
+      assert_equal ["estaciones_de_subte"], results.map(&:category).uniq
+    end
+
+    def test_that_search_filters_by_several_categories
+      results = Epok.search("san martin", categories: %w[estaciones_de_subte estaciones_de_ferrocarril])
+
+      assert_equal %w[estaciones_de_ferrocarril estaciones_de_subte], results.map(&:category).uniq.sort
+    end
+
+    def test_that_search_limits_results
+      assert_equal 2, Epok.search("san martin", limit: 2).count
+    end
+
     private
 
     def result
-      results = Search.new("garicoits")
-      results.first
+      Epok.search("garicoits").first
     end
   end
 end

data/test/epok_test.rb

@@ -1,20 +1,13 @@
 require "test_helper"
 
 class EpokTest < Minitest::Test
-  def test_that_search_builds_a_search
-    search = Epok.search("garicoits")
-
-    assert_instance_of Epok::Search, search
-    assert_equal "garicoits", search.query
+  def test_that_search_builds_a_collection
+    assert_instance_of Epok::Collection, Epok.search("garicoits")
   end
 
-  def test_that_geocoder_builds_a_geocoder
+  def test_that_geocoder_builds_a_collection
     obelisco = Epok::Location.new(x: -58.381570, y: -34.603738)
-    geocoder = Epok.geocoder(obelisco, "farmacias")
 
-    assert_instance_of Epok::Geocoder, geocoder
-    assert_equal(-58.381570, geocoder.x)
-    assert_equal(-34.603738, geocoder.y)
-    assert_equal "farmacias", geocoder.categories
+    assert_instance_of Epok::Collection, Epok.geocoder(obelisco, "farmacias")
   end
 end

data/test/test_helper.rb

@@ -4,12 +4,10 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
 require "epok"
 require "minitest/autorun"
-require "minitest/reporters"
 require "vcr"
 
-Minitest::Reporters.use!
-
 VCR.configure do |config|
   config.cassette_library_dir = "test/fixtures"
   config.hook_into :webmock
+  config.default_cassette_options = { record: :new_episodes }
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: epok
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Ariel Rzezak
@@ -23,26 +23,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: minitest-reporters
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.3.6
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.3.6
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -112,12 +92,14 @@ files:
 - epok.gemspec
 - lib/epok.rb
 - lib/epok/api.rb
-- lib/epok/collectable.rb
 - lib/epok/collection.rb
-- lib/epok/geocoder.rb
 - lib/epok/object.rb
-- lib/epok/search.rb
 - lib/epok/version.rb
+- test/epok/api_test.rb
+- test/epok/categories_test.rb
+- test/epok/collection_test.rb
+- test/epok/datos_utiles_test.rb
+- test/epok/geocode_test.rb
 - test/epok/geocoder_test.rb
 - test/epok/object_test.rb
 - test/epok/search_test.rb

data/lib/epok/collectable.rb

@@ -1,17 +0,0 @@
-require "forwardable"
-
-module Epok
-  module Collectable
-    def self.included(base)
-      base.class_eval do
-        extend Forwardable
-
-        def_delegators :results, :entries, :first
-      end
-    end
-
-    def collection(object)
-      Collection.new object
-    end
-  end
-end

data/lib/epok/geocoder.rb

@@ -1,21 +0,0 @@
-module Epok
-  Location = Struct.new(:x, :y, keyword_init: true)
-
-  class Geocoder
-    include Collectable
-
-    attr_reader :x, :y, :categories
-
-    def initialize(location, categories)
-      @x = location.x
-      @y = location.y
-      @categories = categories
-    end
-
-    private
-
-    def results
-      collection API.geocoder(x, y, categories)
-    end
-  end
-end

data/lib/epok/search.rb

@@ -1,17 +0,0 @@
-module Epok
-  class Search
-    include Collectable
-
-    attr_reader :query
-
-    def initialize(query)
-      @query = query
-    end
-
-    private
-
-    def results
-      collection API.search(query)
-    end
-  end
-end