-
Notifications
You must be signed in to change notification settings - Fork 2
/
v1.0.yaml
306 lines (305 loc) · 12.1 KB
/
v1.0.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
openapi: 3.0.0
info:
title: Platform sharing
version: '1.1'
contact:
name: Host Compliance
description: 'Host Compliance API for platform sharing agreement. *Authorization:* Endpoints which require authentication will require an OAuth2 Bearer Token header: `Authorization: Bearer {token}`.'
servers:
# Added by API Auto Mocking Plugin
- description: SwaggerHub API Auto Mocking
url: https://virtserver.swaggerhub.com/Host-Compliance/PlatformSharing/1.0
- url: 'https://api.hostcompliance.com/api/v1/platform-sharing'
paths:
'/{jurisdiction-slug}/listings':
post:
summary: Validate listings within the Host Compliance system
requestBody:
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Listing'
description: Listings array
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Result'
examples:
example-1:
value:
results: []
'413':
description: Request Entity Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
examples:
example-1:
value:
message: Cannot process more than 100 records in one request. Please reduce the number of listings to 100 or less.
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/DataValidationErrorMessage'
examples:
example-1:
value:
message: Data validation error
errors:
'0':
host_email_address:
- Not a valid email address
'429':
description: Too many requests sent, please limit requests to one per second.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
examples:
example-1:
value:
message: Cannot process more than one request per second. Please try again later.
description: Share STR information with Host Compliance
parameters:
- schema:
type: string
name: jurisdiction-slug
in: path
required: true
description: Jurisdiction slug
example: los-angeles-ca
components:
schemas:
SitusAddress:
type: object
description: The complete physical address of the rental unit as provided to the Hosting Platform by the Host. Required for exemption code "02", "03", and "04" only.
properties:
street_address:
type: string
example: 123 Main st.
unit_number:
type: string
example: '42'
locality:
type: string
example: Los Angeles
state_province:
type: string
example: CA
postal_code:
type: string
example: '90210'
country_code:
type: string
example: US
required:
- street_address
- locality
- state_province
- postal_code
- country_code
Listing:
type: object
x-examples: {}
description: Listing object structure expected as API input
properties:
listing_id:
type: string
example: my-listing-id
description: The Unique Permanent Primary Listing ID (as presented in the metadata of the Listing on the primary publicly facing website of the Hosting Platform)
listing_urls:
type: array
items:
type: string
format: uri
example: 'https://listingsite.com/rooms/1234'
description: The Listing URL(s) (i.e. the website address(es) presented in the exact same format(s) as used on the publicly facing website(s) of the Hosting Platform including any affiliate websites)
registration_number:
type: string
description: The Registration Number or Pending Registration Status Number.
example: STR-12345
exemption_code:
type: string
enum: ["01", "02", "03", "04"]
description: >
An exemption status code that explains why the property is not considered a Short-Term Rental subject to the provisions of the Home-Sharing Ordinance. Allowed values:
* `01` - a residential property advertised and rented exclusively for stays longer than 30 consecutive days. For the avoidance of doubt, this exemption code can only apply to Listings for which the Hosting Platform is actively preventing bookings for 29 days or less.
* `02` - a Hotel or Motel
* `03` - a Transient Occupancy Residential Structure
* `04` - a Bed and Breakfast approved pursuant to LAMC 12.24X.12
example: "01"
house_number:
type: string
description: The house number of the address associated with the Registration Number (or Pending Registration Status Number) (i.e. “123” from the address “123 Main Street”). Required if a registration_number is provided and the address contains a house number.
example: '123'
unit_number:
type: string
description: The apartment/suite/unit number of the address associated with the Registration Number (or Pending Registration Status Number) (i.e. “B” from the address “123 Main Street, Apartment B”). Required if a registration_number is provided and the address contains a unit number.
example: 'B'
booking_information:
type: array
description: |
This array must be populated for the following time periods only if a registration_number is provided
- January 1 of the current year through the current day
- The current day through January 1 of next calendar year
- January 1 of the next calendar year through January 1 of the following year _This date range is only required for Appendix A_
items:
$ref: '#/components/schemas/BookingInformation'
unique_host_id:
type: string
description: As presented in the metadata of each Host Profile and/or Listing on the publicly facing website(s) of the Hosting Platform including any affiliate websites, if applicable. Required if exemption code 02, 03, 04 are provided.
example: HOST12345
host_email_address:
type: string
format: email
description: The email address of the Host as provided to the Hosting Platform by the Host. Required if exemption code 02, 03, 04 are provided.
example: [email protected]
situs_address:
$ref: '#/components/schemas/SitusAddress'
required:
- listing_id
- listing_url
Result:
type: object
properties:
listing_id:
type: string
example: my-listing-id
registration_number:
type: string
description: The Registration Number or Pending Registration Status Number.
example: STR-12345
registration_type:
type: string
description: Type of registration
enum:
- regular
- extended
registration_night_cap:
type: integer
description: Night booked cap based on local laws
booking_eligibility:
type: array
items:
$ref: '#/components/schemas/BookingEligibility'
eligibility_reason:
type: string
description: Optional reason explaining the status provided
eligibility_status:
type: string
enum:
- invalid_registration_number
- exempt
- expired_registration
- application_denied
- revoked_or_suspended_registration
- exemption_status_code_invalid
- exceeded_booking_cap
- str_allowed
- other
description: >
Eligibility status for a given time period
* `str_allowed` - Short term rentals are allowed on this listing
* `invalid_registration_number` - The listing lacks a valid City Registration Number or is not provided
* `expired_registration` - The listing has an expired registration
* `application_denied` - The listing has had its pending registration application denied
* `revoked_or_suspended` - The listing has had its registration revoked or suspended
* `exemption_status_code_invalid` - The City determines that the exemption status code is invalid
* `exceeded_booking_cap` - The Host has exceeded the 120 day cap
* `exempt` - The listing is exempt from str policy
* `other` - Other reason for ineligibility
BookingEligibility:
type: object
properties:
start_date:
type: string
format: date
description: Start date of eligibility period (inclusive)
example: '2019-01-01'
end_date:
type: string
format: date
description: End date of eligibility period (exclusive)
example: '2020-01-01'
str_bookings_allowed_through:
type: string
format: date
description: If given, provides the last date that bookings are allowed. If null, all future bookings are allowed.
example: true
str_remaining_nights_available_for_booking:
type: integer
description: Remaining nights available for booking. Negative values indicate the number of nights by which the registration has exceeded its cap.
example: 366
BookingInformation:
type: object
description: Required if registration_number is provided.
properties:
start_date:
type: string
format: date
description: Start date of eligibility period (inclusive)
example: '2019-01-01'
end_date:
type: string
format: date
description: End date of eligibility period (exclusive)
example: '2019-11-01'
str_nights_booked:
type: integer
description: The number of nights the rental unit has been or will be rented within date range, as a Short-Term Rental through the Hosting Platform.
example: 33
ltr_nights_booked:
type: integer
description: |
The number of nights the rental unit has already been rented within date range for non-Short-Term Rental stays through the Hosting Platform in the calendar year.
> This field is only required for Appendix A.
example: 0
required:
- start_date
- end_date
- str_nights_booked
GenericErrorMessage:
type: object
properties:
message:
type: string
description: Generic error message returned by API unsuccessful response
x-examples: {}
DataValidationErrorMessage:
title: DataValidationErrorMessage
type: object
description: Detailed unsuccessful API response in case of any validation errors
properties:
message:
type: string
errors:
type: array
items:
type: object
description: Each key is representing an index of the input array
properties:
'n':
type: object
description: ''
properties:
field_name:
type: array
description: Field name of the input array
items:
type: string