# Listing Description API

**HTTP Method:&#x20;**<mark style="color:green;">**`POST`**</mark>

#### Endpoint: <https://api.listingai.co/v2/create-description><br>

**Example usage:** A JSFiddle is provided here: <https://jsfiddle.net/odecgfzt/>

#### Headers:

* **`Authorization: Bearer <Your_API_Token>`**

*Note: Replace **`<Your_API_Token>`** with the provided authorization token. If you do not provide a token, you can still text the API but it will only work the the address "152 Strachan Ave Toronto Ontario M6J2S9 Canada*

#### Body Parameters:

<table><thead><tr><th width="233">Parameter</th><th width="165">Type</th><th width="354">Description</th><th>Required</th></tr></thead><tbody><tr><td>address</td><td>String</td><td>The address of the property.</td><td>Yes</td></tr><tr><td>propertyType</td><td>String</td><td>The type of property. <br><br>We suggest using values of "detached house", "row house", "apartment","flat","condo","townhouse", "vacant-land", "commercial", "industrial".<br><br>You can provide other values as long as they are sufficiently descriptive.</td><td>Yes</td></tr><tr><td>transactionType</td><td>String</td><td>The type of transaction intended for the property<br><br>Suggested values are "For sale" or "For rent".<br><br>You can provide other values as long as they are sufficiently descriptive.</td><td>Yes</td></tr><tr><td>numberOfBathrooms</td><td>Number</td><td>The total number of bathrooms in the property.<br><br>This should be an integer. If there are none, provide "0".</td><td>Yes</td></tr><tr><td>numberOfBedrooms</td><td>Number</td><td>The total number of bedrooms in the property.<br><br>This should be an integer. If there are none, provide "0".</td><td>Yes</td></tr><tr><td>numberOfParkingSpaces</td><td>Number</td><td>The total number of parking spaces available in the property.<br><br>This should be an integer. If there are none, provide "0".</td><td>Yes</td></tr><tr><td>additionalDetails</td><td>String</td><td>Additional information about the property that could be beneficial to include in the description.<br><br>This is a free text area. You can provde any notes you feel are relevant.</td><td>No</td></tr><tr><td>area</td><td>Number</td><td>The total area of the interior space of the property<br><br>This should be a value representing a square figure such as "2500" or "250" etc.</td><td>No</td></tr><tr><td>areaUnit</td><td>String</td><td>The unit of measurement for the area of the property.<br><br>Suggeste values are sqft or sqm.</td><td>No</td></tr><tr><td>lotSize</td><td>String</td><td>The size of the land the property is located on.<br><br>You can provide dimensions such as "10x30" or square figures such as "2500"</td><td>No</td></tr><tr><td>lotSizeUnit</td><td>String</td><td>The unit of measurement for the lot size.<br><br>Suggested values are acres, sqm, sqft, hectares</td><td>No</td></tr><tr><td>length</td><td>Number</td><td><p>The approximate number of words to be used in the description.<br><br>Word limit is 2,000</p><p>Character limit is 10,000<br><br>You must provide either this field OR the characterCount field</p></td><td>Yes</td></tr><tr><td>lengthType</td><td>String</td><td>"words" or "characters"</td><td>Yes</td></tr><tr><td>language</td><td>String</td><td>The language in which the description should be generated.<br><br>Any ISO 639 language code and ISO 3166-1 Alpha-2 country code i.e. en-US, en-UK, fr-CA</td><td>Yes</td></tr><tr><td>writingStyle</td><td>String</td><td>Relaxed, formal, luxury or custom</td><td>Yes</td></tr><tr><td>tone</td><td>String</td><td>Ignored unless writing style is "custom"</td><td>No</td></tr><tr><td>complexity</td><td>String</td><td>Ignored unless writing style is "custom"</td><td>No</td></tr><tr><td>copyWriter</td><td>String</td><td>avery, blake, casey, dakota, emerson [all lower case]<br><br>Recommend using avery or blake for best results. <br><br>Ratings as of July 23rd 2024:<br>Avery: 4.76<br>Blake: 4.75<br>Casey: 3.2<br>Dakota: 3.1<br>Emerson: 4</td><td>Yes</td></tr><tr><td>instructions</td><td>Array[ String]</td><td><p>Array of strings containing instructions for the AI to implement when writing. <br><br>Example input:</p><p><br>["Do not include the zip code when mentioning the address", "Do not mention the listing price"]</p></td><td>Yes</td></tr><tr><td>dictionaryRules</td><td>Array[rule]</td><td><p>Example input:</p><p></p><p>[{"type":"substitute term","term":"master bedroom",alternative:"primary bedroom"}]<br><br>Supported types: "substitute term" and "encourage using the term"<br><br>Only when substituting a term is the "alternative" field required on the rule.</p></td><td>Yes</td></tr><tr><td>communityHighlightsDiscovery</td><td>String</td><td><p>Acceptable values are "disabled", "point", "city" or "property_address"<br><br>NB In order to use "property_address" you will need to be granted special permission as the supporting location data is very expensive if using a large volume of unique addresses. We encourage people with large volumes to use "city" or provide a consistent point that represent the community location.</p><p></p><p>By default auto discovery is disabled, any passed in communityHighlights will be used.<br></p></td><td>No, defaults to "disabled"</td></tr><tr><td>communityHighlights</td><td>Array[locations]</td><td>If data is provided in this field, automated discovery of community highlights will not occur regardless of the value provided in the communityHighlightsDiscovery field.<br><br>These should be in an array with objects formatted the same as a Google Places API  location results.<br><br>Further reading: <a href="https://developers.google.com/maps/documentation/places/web-service/place-id#places-api">https://developers.google.com/maps/documentation/places/web-service/place-id#places-api</a><br><br>Example input:<br><br>[{"type":"Feature","geometry":{"type":"Point","coordinates":[-74.0109927,40.705751]},"name":"Leman Manhattan Preparatory School","place_name":"41 Broad Street, New York","category":"secondary_school","distance":518.310481413427}]</td><td>No<br><br></td></tr><tr><td>communityLongitude</td><td>Decimal</td><td>This is only required when "communityHighlightsDiscovery" is set to "point". In all other cases this value is ignored.<br><br>Discovered community location data will be based on this as the centre of the search location.<br><br>Example value: -79.4129782</td><td></td></tr><tr><td>communityLatitude</td><td>Decimal</td><td>This is only required when "communityHighlightsDiscovery" is set to "point". In all other cases this value is ignored.<br><br>Discovered community location data will be based on this as the centre of the search location.<br><br>Example value: 43.6442542</td><td></td></tr></tbody></table>

#### **Response:**

The response will be an AI-generated real estate description based on the input parameters.

{% code overflow="wrap" %}

```json
{
    "status": "success",
    "response": "Welcome to 123 John Bon Jovi Blvd! This spacious 4-bedroom, 5-bathroom house offers an incredible opportunity. With a barter transaction type, seize the chance to make a creative exchange.  Spanning an impressive 4,500 square feet, this house provides ample room for all your needs. Whether you're looking to unwind in the comfort of your living room or host a gathering, there's plenty of space for activities.  The kitchen is thoughtfully designed, offering functionality and style. Prepare culinary masterpieces with ease using the modern appliances and abundant countertop space.  Each of the 5 bathrooms showcases tasteful finishes and fixtures, ensuring comfort and convenience for everyone in the household.  As you explore the rooms, you'll find that each bedroom offers privacy and personal space. The possibilities are endless when it comes to transforming these rooms into cozy sanctuaries or functional workspaces.  The outdoor area presents a delightful canvas for your imagination. From hosting backyard barbecues to creating a tranquil garden retreat, the possibilities for outdoor enjoyment are limitless.  Additional features and details of this property are waiting to be discovered.  With a neutral writing style, this inclusive listing aims to appeal to a diverse range of potential buyers or renters. Don't miss out on the opportunity to make this property yours. Contact us today to schedule a viewing at 123 John Bon Jovi Blvd."
}
```

{% endcode %}