Retrieve a listing
Aufruf, Parameter, Antwort und Fehler von GET /v1/listings/{externalListingId}.
Zuletzt aktualisiert:
Braucht den Scope read.
Aufruf
GET https://api.athaus.ai/v1/listings/{externalListingId}Parameter
Pfad
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
externalListingId | string | ja | Your reference of the listing: the value of metadata.source.offererMarketingKey. A listing without one has its own listingId here, and the listingId always works in the path. 1 to 128 letters, digits, dots, underscores or hyphens, not starting or ending with a dot. |
Kopf
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
Athaus-Version | string | nein | Optional and carries nothing a client needs: the version is the path. Accepted when it says v1 or 1. Any other value is a 400 api_version_unsupported. |
If-None-Match | string | nein | An ETag you hold. If it is still current, the answer is 304 without a body. |
Beispiel
curl "https://api.athaus.ai/v1/listings/WE-12" \
-H "Authorization: Bearer ath_live_..."Antwort
Bei Erfolg kommt 200 mit ListingResponse.
ListingResponse
| Feld | Typ | Beschreibung |
|---|---|---|
listing | object | The listing as stored. data, metadata, contact and media are the OpenImmo 2.0 members; listingId, status, createdAt and updatedAt are our additive members (status: publication state in Athaus, closed means sold or let). |
listing.data | object | |
listing.data.estateType | string | Eines von HOUSE, APARTMENT, PLOT, OFFICE, TRADING, GASTRONOMY_HOTEL, STORAGE_PRODUCTION, AGRICULTURE_FORESTRY, PARKING, SENIOR, PROJECT, MISCELLANEOUS. |
listing.data.estateSubType | object | |
listing.data.distributionType | string | Eines von BUY, RENT, COMPULSORY_AUCTION, BUY_AUCTION. |
listing.data.location | object | |
listing.data.location.postalcode | string | |
listing.data.location.city | string | |
listing.data.location.street | string | |
listing.data.location.houseNumber | string | |
listing.data.location.unit | string | |
listing.data.location.staircase | string | |
listing.data.location.floorNumber | integer | -5 bis 999. |
listing.data.location.entrance | string | |
listing.data.location.state | string | |
listing.data.location.country | string | Eine von 249 Angaben der Liste im Standard. |
listing.data.location.geometry | object | |
listing.data.location.showAddress | boolean | Vorgabe true. |
listing.data.location.locationNote | map<string> | |
listing.data.prices | object | |
listing.data.prices.currency | string | Eine von 180 Angaben der Liste im Standard. Vorgabe EUR. |
listing.data.prices.buy | object | |
listing.data.prices.rent | object | |
listing.data.prices.compulsoryAuction | object | |
listing.data.prices.buyAuction | object | |
listing.data.prices.brokerageFee | any | |
listing.data.prices.showPrice | boolean | |
listing.data.prices.priceNote | map<string> | |
listing.data.prices.countrySpecific | object | |
listing.data.spaces | object | |
listing.data.spaces.spaceMeasureUnit | string | Eines von SQUARE_METER, SQUARE_INCH, SQUARE_FOOT, SQUARE_YARD, HECTARE, ACRE. Vorgabe SQUARE_METER. |
listing.data.spaces.buildingFront | number | 0 bis 99999999. |
listing.data.spaces.kitchenSpace | number | 0 bis 99999999. |
listing.data.spaces.overallSpace | number | 0 bis 99999999. |
listing.data.spaces.usableFloorSpace | number | 0 bis 99999999. |
listing.data.spaces.spaceMax | number | 0 bis 99999999. |
listing.data.spaces.spaceMin | number | 0 bis 99999999. |
listing.data.spaces.plotSpace | number | 0 bis 99999999. |
listing.data.spaces.plotFront | number | 0 bis 99999999. |
listing.data.spaces.additionalSpace | number | 0 bis 99999999. |
listing.data.spaces.residential | object | |
listing.data.spaces.commercial | object | |
listing.data.conditions | object | |
listing.data.conditions.buildState | string | Eines von FIRST_TIME_USE, FIRST_TIME_USE_AFTER_REFURBISHMENT, MINT_CONDITION, MODERNISED, REFURBISHED, FULLY_RENOVATED, PARTLY_RENOVATED, NEED_OF_RENOVATION, WELL_KEPT, NEGOTIABLE, RIPE_FOR_DEMOLITION, PROJECTED, NO_INFORMATION, RESTRUCTURED, TO_RESTORE, TO_REFURBISH. |
listing.data.conditions.ageState | string | Eines von OLD, NEW. |
listing.data.conditions.lastModernisation | integer | |
listing.data.conditions.constructionStyle | string | Eines von PREFABRICATED, SOLID, SOLID_PREFABRICATED, TIMBERHOUSE, WOOD_PREFABRICATED, UNSPECIFIED. |
listing.data.conditions.yearOfConstruction | integer | 1000 bis 3000. |
listing.data.energy | object | |
listing.data.energy.energyType | object | |
listing.data.energy.countrySpecific | object | |
listing.data.features | object | |
listing.data.features.accessibleFromStreet | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.aircondition | string | Eines von YES, PART, NO, NOT_APPLICABLE. |
listing.data.features.entranceHall | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.floorCovering | object | |
listing.data.features.furnished | string | Eines von PART, FULL, NO, NOT_APPLICABLE. |
listing.data.features.garden | object | |
listing.data.features.gym | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.internet | object | |
listing.data.features.lighting | object | |
listing.data.features.mezzanine | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.propertyOrientation | string | Eines von NORTH, EAST, SOUTH, WEST, NORTH_EAST, SOUTH_EAST, SOUTH_WEST, NORTH_WEST. |
listing.data.features.receptionist | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.security | object | |
listing.data.features.wheelchairUse | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.wineCellar | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.features.residential | object | |
listing.data.features.commercial | object | |
listing.data.features.parking | object | |
listing.data.features.plot | object | |
listing.data.structure | object | |
listing.data.structure.building | object | |
listing.data.structure.rooms | object | |
listing.data.structure.commercial | object | |
listing.data.structure.parkingLots | object | |
listing.data.texts | object | |
listing.data.texts.headline | map<string> | |
listing.data.texts.description | map<string> | |
listing.data.texts.features | map<string> | |
listing.data.texts.extendedInformation | map<string> | |
listing.data.texts.area | map<string> | |
listing.data.management | object | |
listing.data.management.isImmediatelyAvailable | boolean | |
listing.data.management.availableFrom | string (date) | |
listing.data.management.availableUntil | string (date) | |
listing.data.management.isForInvestment | boolean | |
listing.data.management.heritageProtected | string | Eines von YES, NO, NOT_APPLICABLE. |
listing.data.management.marketStatus | string | Eines von SOLD, RENTED, REFERENCE, RESERVED, UNDER_OFFER. |
listing.data.management.projectStatus | string | Eines von BUILDING_PERMISSION, COMMERCIAL_LAUNCH, CONSTRUCTION_START, UNDER_CONSTRUCTION, SHELL_WORKS, FINISHING_WORKS, LAST_CHANCE, PROJECT_ENDED. |
listing.data.management.marketLabel | string | |
listing.data.management.isRented | boolean | |
listing.data.management.useFor | string | Eines von LIVING, COMMERCIAL, MIXED, OFFICE, INDUSTRIAL. |
listing.data.management.isForHolidayRental | boolean | |
listing.data.management.rent | object | |
listing.data.management.compulsoryAuction | object | |
listing.data.countrySpecific | object | |
listing.data.countrySpecific.de | object | |
listing.data.countrySpecific.fr | object | |
listing.data.contact | object | |
listing.data.contact.salutation | string | Eines von Mr, Mrs, Miss, Ms, Mx, Sir, Dame, Dr, Cllr, Lady, Lord. |
listing.data.contact.firstName | string | |
listing.data.contact.lastName | string | |
listing.data.contact.name | string | |
listing.data.contact.emailAddress | string | |
listing.data.contact.phoneNumber | string | |
listing.data.contact.mobilePhoneNumber | string | |
listing.data.contact.imageURL | string | |
listing.data.contact.userHomepage | string | |
listing.data.contact.postalCode | string | |
listing.data.contact.city | string | |
listing.data.contact.street | string | |
listing.data.contact.houseNumber | string | |
listing.data.contact.country | string | |
listing.data.contact.preferredContactType | string | Eines von ANONYMOUS, BY_PHONE, BY_EMAIL, OWN_WEBSITE. |
listing.data.contact.contactNote | map<string> | |
listing.data.contact.displayedInformation | object | |
listing.data.links | object | |
listing.data.links.externalLinks | object[] | |
listing.data.links.virtualTours | object[] | |
listing.metadata | object | |
listing.metadata.source | object | |
listing.metadata.source.offererMarketingKey | string | |
listing.metadata.source.offererEstateId | string | |
listing.metadata.source.offererEstateGroupId | string | |
listing.metadata.portalWebKey | string | |
listing.contact | object | |
listing.contact.salutation | string | Eines von Mr, Mrs, Miss, Ms, Mx, Sir, Dame, Dr, Cllr, Lady, Lord. |
listing.contact.firstName | string | |
listing.contact.lastName | string | |
listing.contact.name | string | |
listing.contact.emailAddress | string | |
listing.contact.phoneNumber | string | |
listing.contact.mobilePhoneNumber | string | |
listing.contact.imageURL | string | |
listing.contact.userHomepage | string | |
listing.contact.postalCode | string | |
listing.contact.city | string | |
listing.contact.street | string | |
listing.contact.houseNumber | string | |
listing.contact.country | string | |
listing.contact.preferredContactType | string | Eines von ANONYMOUS, BY_PHONE, BY_EMAIL, OWN_WEBSITE. |
listing.contact.contactNote | map<string> | |
listing.contact.displayedInformation | object | |
listing.contact.displayedInformation.mainContactPerson | object | |
listing.contact.displayedInformation.additionalContactPerson | object | |
listing.media | object[] | |
listing.media[].externalMediaId | string | |
listing.media[].title | string | |
listing.media[].id | string (uuid) | The id of the file in /files. |
listing.media[].kind | string | Eines von photo, floor_plan, document. |
listing.media[].documentType | string | |
listing.media[].fileName | string | |
listing.media[].mimeType | string | |
listing.media[].sizeBytes | integer | |
listing.media[].width | integer | |
listing.media[].height | integer | |
listing.media[].contentUrl | string | The address of the bytes; fetch it with the same API key. |
listing.userDefined | object[] | |
listing.userDefined[].name | string | |
listing.userDefined[].value | string | |
listing.userDefined[].utyp | string | Eines von string, integer, boolean, decimal. |
listing.userDefined[].modus | string | |
listing.listingId | string (uuid) | |
listing.projectId | string (uuid) | Present when the listing is a unit of a new-build project: the projectId of that project. Read-only; POST /projects/{externalProjectId}/assign moves a listing into a project. |
listing.status | string | Eines von draft, active, paused, reserved, closed. |
listing.createdAt | string (date-time) | |
listing.updatedAt | string (date-time) |
Köpfe der Antwort
| Kopf | Beschreibung |
|---|---|
Request-Id | Identifies this request. Quote it in a support request. |
Athaus-Version | The API version of this response: v1. |
Athaus-Release | The release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it. |
ETag | A strong entity tag of this state of the resource. Send it as If-Match to change or delete the resource only if it is unchanged, or as If-None-Match to read it only if it changed. |
RateLimit-Policy | The quota policy of the bucket that applies. |
RateLimit | Remaining quota and seconds until the bucket is full again. |
Mit If-None-Match auf den aktuellen ETag antwortet die Operation 304 ohne Rumpf.
Fehler
Jeder Fehler kommt als Problem Details. Verzweige auf code, nicht auf title oder detail.
| Status | Codes | Bedeutung |
|---|---|---|
400 | api_version_unsupported, invalid_input | Invalid request. |
401 | unauthorized | Missing or invalid API key. |
403 | insufficient_permissions, plan_required | The key lacks a right, or the plan does not include API access. |
404 | not_found | Nothing under this ID. |
429 | rate_limited | Rate limit exceeded. |
500 | internal_error | Server error. |
Weiter lesen
REST-API: Anmeldung mit einem API-Key
Jeder Aufruf von /v1 trägt einen API-Key als Bearer-Token. Wo du ihn bekommst, welche Scopes er trägt und was nicht geht.
REST-API: Fehler als Problem Details
Jeder Fehler von /v1 ist ein Problem nach RFC 9457 mit echtem HTTP-Status, einem Code zum Verzweigen und einer Request-Id für den Support.