Skip to content

Local Hero

Instruction

The Local Hero is offering agents a free listing spot on top of the result list in the respective borough for 24 hours in exchange for exclusivity during this time. Supported real estate types are HOUSE_RENT, HOUSE_BUY, APARTMENT_RENT, and APARTMENT_BUY.

Note: For using the LocalHero endpoints, your API client needs to have the scopes S_LOCALHERO_READ and S_LOCALHERO_WRITE assigned. To request it, please use this form.

There are two endpoints: checkslot and bookslot. For booking a LocalHero object, you need to perform two steps. First, check if a slot is available in a certain area using the checkslot endpoint. If the response is true, you can use the bookslot endpoint for booking.

STEP 1: Check Slot Endpoint

Method: POST
URL: /api/localhero/v2/checkslot
Content-Type: application/json

Description:

The Check Slot endpoint allows you to check if a time slot is available for a specific property in a selected geographic area. You need to provide the coordinates of the desired location along with the property type to check the availability.

Request:

In the request body, provide the following information in JSON format. You can deliver either the address of the object or the location. If both are provided, the location data will be used.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "address": {
    "street": "Andreasstr",
    "houseNumber": "10",
    "postcode": "10243",
    "city": "Berlin",
    "countryCode": "DE"
  },
  "location": {
    "latitude": 52.51261,
    "longitude": 13.43145
  },
  "realEstateType": "APARTMENT_BUY"
}
  • address: Object containing address details.
  • location: An object containing the latitude and longitude of the location.
  • realEstateType: The type of property for which you want to check the slot (e.g., APARTMENT_BUY, HOUSE_RENT).

Response:

The response is returned in JSON format and includes the availability status of the time slot.

1
2
3
{
  "slotAvailable": true
}
  • slotAvailable: A boolean value indicating whether a time slot is available (true = slot available, false = slot not available).

Possible Errors

  • The status 400 is thrown if the realEstateType is not one of HOUSE_RENT, HOUSE_BUY, APARTMENT_RENT, or APARTMENT_BUY.

STEP 2: Book Slot Endpoint

Method: POST
URL: /api/localhero/v2/bookslot
Content-Type: application/json

Description:

The Book Slot endpoint allows you to book a time slot for a specific property based on the provided location and property type. If the slot is unavailable, the API will return a response indicating that the slot could not be booked.

Request:

In the request body, provide the following information in JSON format:

1
2
3
{
  "scoutId": "12345678"
}
  • scoutId: A unique identifier for the user (scout) attempting to make the booking.

Response:

The response is returned in JSON format and includes details of the booking status.

1
2
3
4
5
{
  "bookingStatus": "BOOKED",
  "bookingId": "64f1bc68-76b4-4980-92E7-1b41082bfe44",
  "bookedUntil": "2022-12-30T12:19:20.404221+01:00"
}
  • bookingStatus: Indicates whether the slot was successfully booked (e.g., BOOKED, NOT_BOOKED).
  • bookingId: A unique identifier for the booking. This ID can be used for future reference or to manage the booking.
  • bookedUntil: The date and time until which the booking is valid.

If a slot cannot be booked, the API will return a response indicating that the booking could not be made.

1
2
3
{
  "bookingStatus": "FAILED"
}

Possible Errors

  • The status 404 is thrown if the scoutId doesn’t exist.
  • The status 500 is thrown if the type of the real estate identified by scoutId is not one of HOUSE_RENT, HOUSE_BUY, APARTMENT_RENT, or APARTMENT_BUY.