Retrieve a project
Request, parameters, response and errors of GET /v1/projects/{externalProjectId}.
Last updated:
Returns the project in the OpenImmo 2.0 shape. data.units carries the figures of its units (their number, price and area range); the units themselves are listings, named by assignedListings (ours, not OpenImmo; a project holds at most 1000 units, so the list is never longer) and readable with GET /listings/{externalListingId}, where projectId marks them. Needs read access to projects.
Requires the scope read and at least the level read on projects.
Request
GET https://api.athaus.ai/v1/projects/{externalProjectId}Parameters
Path
| Name | Type | Required | Description |
|---|---|---|---|
externalProjectId | string | yes | Your reference of the project: the value of metadata.source.offererMarketingKey. A project without one has its own projectId here, and the projectId always works in the path. 1 to 128 letters, digits, dots, underscores or hyphens, not starting or ending with a dot. |
Header
| Name | Type | Required | Description |
|---|---|---|---|
Athaus-Version | string | no | 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 | no | An ETag you hold. If it is still current, the answer is 304 without a body. |
Example
curl "https://api.athaus.ai/v1/projects/PRJ-1-ext" \
-H "Authorization: Bearer ath_live_..."Response
On success the status is 200 with ProjectResponse.
ProjectResponse
| Field | Type | Description |
|---|---|---|
projectId | string (uuid) | Ours, not OpenImmo: the id Athaus gave the project; it always works in the path. |
status | string | any | Ours, not OpenImmo: the project state of the office, by name. |
createdAt | string (date-time) | |
updatedAt | string (date-time) | |
data | object | |
data.estateType | string | One of NEW_BUILD_PROJECT, NEW_HOME_PROJECT. |
data.estateSubType | string | object | null | any | |
data.distributionType | string | One of BUY, RENT, BUY_RENT. |
data.units | object | |
data.units.numberOfUnits | number | 0 to 999999. |
data.units.priceFrom | number | 0 to . |
data.units.priceTo | number | 0 to . |
data.units.livingSpaceFrom | number | 0 to . |
data.units.livingSpaceTo | number | 0 to . |
data.units.numberOfRoomsFrom | number | 0 to . |
data.units.numberOfRoomsTo | number | 0 to . |
data.units.furnishingLevel | string | One of NOT_PROVIDED, STANDARD, UPSCALE, FULL. |
data.units.provisionType | string | One of PROVISION_FREE, PROVISION_FOR_BUYER, NOT_PROVIDED. |
data.units.provisionPercent | number | 0 to . |
data.units.provisionIsVatIncluded | string | One of YES, NO, NOT_PROVIDED. |
data.units.soldOutPercentage | number | 0 to . |
data.location | object | |
data.location.postalcode | string | |
data.location.city | string | |
data.location.street | string | |
data.location.houseNumber | string | |
data.location.unit | string | |
data.location.staircase | string | |
data.location.floorNumber | integer | -5 to 999. |
data.location.entrance | string | |
data.location.state | string | |
data.location.country | string | One of 249 values from the list in the standard. |
data.location.geometry | object | |
data.location.geometry.type | string | Always Point. |
data.location.geometry.coordinates | number[] | |
data.location.showAddress | boolean | Default true. |
data.location.locationNote | map<string> | |
data.program | object | |
data.program.projectStatus | string | One of CONSTRUCTION_START, PROJECT_ENDED. |
data.deliveryDate | string | |
data.structure | object | |
data.structure.building | object | |
data.structure.building.numberOfFloors | integer | 1 to 999. |
data.texts | object | |
data.texts.headline | map<string> | |
data.texts.description | map<string> | |
data.texts.features | map<string> | |
data.texts.extendedInformation | map<string> | |
data.texts.area | map<string> | |
data.links | object | |
data.links.externalLinks | object[] | |
data.links.externalLinks[].url | string | |
data.links.externalLinks[].urlType | string | One of MAP, MOVIE, PANORAMA, REVOCATION_INSTRUCTION, OFFERER_DETAIL_PAGE. |
data.links.externalLinks[].title | string | |
data.links.virtualTours | object[] | |
data.links.virtualTours[].url | string | |
data.links.virtualTours[].provider | string | |
data.links.virtualTours[].title | string | |
data.contact | object | |
data.contact.salutation | string | One of Mr, Mrs, Miss, Ms, Mx, Sir, Dame, Dr, Cllr, Lady, Lord. |
data.contact.firstName | string | |
data.contact.lastName | string | |
data.contact.name | string | |
data.contact.emailAddress | string | |
data.contact.phoneNumber | string | |
data.contact.mobilePhoneNumber | string | |
data.contact.imageURL | string | |
data.contact.userHomepage | string | |
data.contact.postalCode | string | |
data.contact.city | string | |
data.contact.street | string | |
data.contact.houseNumber | string | |
data.contact.country | string | |
data.contact.preferredContactType | string | One of ANONYMOUS, BY_PHONE, BY_EMAIL, OWN_WEBSITE. |
data.contact.contactNote | map<string> | |
data.contact.displayedInformation | object | |
data.contact.displayedInformation.mainContactPerson | object | |
data.contact.displayedInformation.additionalContactPerson | object | |
metadata | object | |
metadata.source | object | |
metadata.source.offererMarketingKey | string | |
metadata.source.offererEstateId | string | |
metadata.portalWebKey | string | |
assignedListings | object[] | |
assignedListings[].externalListingId | string |
Response headers
| Header | Description |
|---|---|
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. |
With If-None-Match naming the current ETag, the operation answers 304 without a body.
Errors
Every error arrives as problem details. Branch on code, not on title or detail.
| Status | Codes | Meaning |
|---|---|---|
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. |
Keep reading
REST API: authentication with an API key
Every call to /v1 carries an API key as a bearer token. Where to get one, which scopes it carries and what does not work.
REST API: errors as problem details
Every error from /v1 is an RFC 9457 problem with a real HTTP status, a code to branch on and a request id for support.