{"openapi":"3.1.0","info":{"title":"Oscar Property API","description":"Look up a property by address. Get our measurements of it, and a map of the property to show on your own website. Guide: https://api.dev.oscardata.com/api/v1/docs","version":"1"},"servers":[{"url":"https://api.dev.oscardata.com"}],"paths":{"/api/v1/property":{"get":{"summary":"Get a property's measurements and map","description":"One property: the measurements in `fields` and a map of `layers`.\n\nGive exactly one of `address` (any US street address; we return our best\nmatch and grade it in `match`) or `property_id` (from an earlier\nresponse; no address lookup). `fields` (comma-separated, e.g. `lawn`)\nselects metrics; `layers` (e.g. `lawn,property`) selects the overlays of\nthe embed map. Ask for at least one. `units` is `sqft` (default) or `m2`.","operationId":"get_property_api_v1_property_get","parameters":[{"name":"address","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A US street address.","examples":["123 Example Street, Anytown, NY 10001"],"title":"Address"},"description":"A US street address."},{"name":"property_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`property_id` from an earlier response.","title":"Property Id"},"description":"`property_id` from an earlier response."},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated measurements to return. Available: `lawn`.","examples":["lawn"],"title":"Fields"},"description":"Comma-separated measurements to return. Available: `lawn`."},{"name":"layers","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated overlays for the embedded map. Available: `lawn`, `property` (the property boundary).","examples":["lawn,property"],"title":"Layers"},"description":"Comma-separated overlays for the embedded map. Available: `lawn`, `property` (the property boundary)."},{"name":"units","in":"query","required":false,"schema":{"type":"string","description":"Units for areas: `sqft` (default) or `m2`.","default":"sqft","title":"Units"},"description":"Units for areas: `sqft` (default) or `m2`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyResponse"}}}},"400":{"description":"Bad parameters (unknown field, layer, or unit)"},"401":{"description":"Missing, invalid, or revoked API key"},"403":{"description":"The company is archived"},"404":{"description":"No property found in your company's ZIP codes"},"422":{"description":"No measurement for a field or layer you asked for (`detail.code` is `not_measured`)"},"429":{"description":"More than 60 requests a minute; see Retry-After"}}}}},"components":{"schemas":{"Embed":{"properties":{"url":{"type":"string","title":"Url","description":"The map page. Put it in the `src` of an `<iframe>` on your page. It needs no API key, so it is safe to use in a browser."},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When `url` stops working, in UTC: one hour after your request. Call the API again for a new link."}},"type":"object","required":["url","expires_at"],"title":"Embed","description":"A link to a map of the property that shows the layers you asked for.\nOnly when you send `layers`."},"LawnMetric":{"properties":{"area":{"anyOf":[{"type":"integer"},{"type":"number"}],"title":"Area","description":"The lawn area of the property, in `unit`: the property minus buildings, driveways, sidewalks and other paving. It includes grass under trees, so the true grass area can be smaller. Whole square feet, or square metres to one decimal place."},"unit":{"type":"string","enum":["sqft","m2"],"title":"Unit","description":"The unit of `area`: `sqft` (square feet) or `m2` (square metres). It is what you sent in `units`, or `sqft` if you did not send `units`."},"percent_of_property":{"type":"number","title":"Percent Of Property","description":"How much of the property is lawn, as a percent from 0 to 100, to one decimal place. For example, `38.5` means the lawn covers 38.5 % of the property's area."}},"type":"object","required":["area","unit","percent_of_property"],"title":"LawnMetric","description":"The lawn measurement. Without one the request fails with 422\n`not_measured`."},"Match":{"properties":{"quality":{"type":"string","enum":["exact","approximate","low"],"title":"Quality","description":"`exact`, `approximate` or `low`. With `exact`, every check passed. With `approximate` or `low`, ask your user to confirm the property."},"reasons":{"items":{"type":"string"},"type":"array","title":"Reasons","description":"The checks that failed, for example `[\"number_mismatch\"]`. Empty when `quality` is `exact`. Values: `partial_match`, `interpolated`, `no_house_number`, `number_mismatch`, `postal_mismatch`, `nearest_lot`, `text_search`, `unit`."}},"type":"object","required":["quality","reasons"],"title":"Match","description":"How well the address you sent matches the property we found. Only when\nyou send `address`, not `property_id`."},"Metrics":{"properties":{"lawn":{"anyOf":[{"$ref":"#/components/schemas/LawnMetric"},{"type":"null"}]}},"type":"object","title":"Metrics","description":"The measurements you asked for in `fields`, one object for each name.\nOnly when you send `fields`."},"PropertyResponse":{"properties":{"property_id":{"type":"string","title":"Property Id","description":"Our ID for the property, a UUID. It never changes for the same property. Store it and send it as `property_id` next time: you get the same property back, without an address lookup."},"matched_address":{"type":"string","title":"Matched Address","description":"The property's address in our records, for example `123 EXAMPLE ST, Anytown, NY 10001`. It can be written differently from the address you sent. Show it to your user so they can check we found the right property."},"match":{"anyOf":[{"$ref":"#/components/schemas/Match"},{"type":"null"}],"description":"How well the address you sent matches the property we found. Only when you send `address`."},"metrics":{"anyOf":[{"$ref":"#/components/schemas/Metrics"},{"type":"null"}],"description":"The measurements you asked for in `fields`, one object for each name. Only when you send `fields`."},"embed":{"anyOf":[{"$ref":"#/components/schemas/Embed"},{"type":"null"}],"description":"A link to a map of the property. Only when you send `layers`."}},"type":"object","required":["property_id","matched_address"],"title":"PropertyResponse"}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Your company API key: `Authorization: Bearer osk_…`"}}},"security":[{"apiKey":[]}]}