Class: Craigslist::API::ZipLocation

Inherits:
Object
  • Object
show all
Defined in:
lib/craigslist/api/zip_location.rb

Overview

Where a US ZIP code maps to on craigslist.

Carries a subarea when the ZIP resolves to one. That matters more than it looks: subarea is required in every area that has subareas, and omitting it is the most common reason a posting comes back NOT_VALID.

Examples:

Feeding a posting directly

place = client.area_for_zip("94110")
place.area      #=> "sfo"
place.subarea   #=> "sfc"

Craigslist::API::Posting.new(**place.to_h, key: ..., title: ...)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(area: nil, area_description: nil, subarea: nil, subarea_description: nil) ⇒ ZipLocation

Returns a new instance of ZipLocation.



30
31
32
33
34
35
36
 
# File 'lib/craigslist/api/zip_location.rb', line 30

def initialize(area: nil, area_description: nil, subarea: nil, subarea_description: nil)
  @area = area
  @area_description = area_description
  @subarea = subarea
  @subarea_description = subarea_description
  freeze
end

Instance Attribute Details

#area ⇒ String? (readonly)

Returns area abbreviation, e.g. "sfo".

Returns:

  • (String, nil) —

    area abbreviation, e.g. "sfo"



19
20
21
 
# File 'lib/craigslist/api/zip_location.rb', line 19

def area
  @area
end

#area_description ⇒ String? (readonly)

Returns e.g. "SF bay area".

Returns:

  • (String, nil) —

    e.g. "SF bay area"



22
23
24
 
# File 'lib/craigslist/api/zip_location.rb', line 22

def area_description
  @area_description
end

#subarea ⇒ String? (readonly)

Returns subarea abbreviation, e.g. "sfc".

Returns:

  • (String, nil) —

    subarea abbreviation, e.g. "sfc"



25
26
27
 
# File 'lib/craigslist/api/zip_location.rb', line 25

def subarea
  @subarea
end

#subarea_description ⇒ String? (readonly)

Returns e.g. "city of san francisco".

Returns:

  • (String, nil) —

    e.g. "city of san francisco"



28
29
30
 
# File 'lib/craigslist/api/zip_location.rb', line 28

def subarea_description
  @subarea_description
end

Class Method Details

.from(data) ⇒ ZipLocation

Builds from the endpoint payload.

The live API nests under "area" and "subarea". The published OpenAPI spec documents a flat shape instead, so both are accepted.

Parameters:

  • data (Hash, nil)

Returns:



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/craigslist/api/zip_location.rb', line 45

def self.from(data)
  data ||= {}
  nested = data["area"]

  if nested.is_a?(Hash)
    sub = data["subarea"].is_a?(Hash) ? data["subarea"] : {}
    new(
      area: nested["abbreviation"],
      area_description: nested["description"],
      subarea: sub["abbreviation"],
      subarea_description: sub["description"]
    )
  else
    new(area: data["abbreviation"], area_description: data["description"])
  end
end

Instance Method Details

#inspect ⇒ Object 



75
76
77
 
# File 'lib/craigslist/api/zip_location.rb', line 75

def inspect
  "#<#{self.class.name} area=#{area.inspect} subarea=#{subarea.inspect}>"
end

#subarea? ⇒ Boolean

Returns whether this ZIP resolved to a subarea.

Returns:

  • (Boolean) —

    whether this ZIP resolved to a subarea



63
64
65
 
# File 'lib/craigslist/api/zip_location.rb', line 63

def subarea?
  !subarea.nil?
end

#to_h ⇒ Hash

Posting keywords, ready to splat. Omits :subarea when there is none, rather than passing an explicit nil.

Returns:

  • (Hash) 


71
72
73
 
# File 'lib/craigslist/api/zip_location.rb', line 71

def to_h
  subarea? ? {area: area, subarea: subarea} : {area: area}
end