Listing Description API

This API provides a way to generate AI-based descriptions for real estate listings. It takes various attributes of the property as inputs and uses them to generate a detailed description.

HTTP Method: POST

Endpoint: https://api.listingai.co/v2/create-description

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:

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

Parameter

Type

Description

Required

address

String

The address of the property.

Yes

propertyType

String

The type of property. We suggest using values of "detached house", "row house", "apartment","flat","condo","townhouse", "vacant-land", "commercial", "industrial". You can provide other values as long as they are sufficiently descriptive.

Yes

transactionType

String

The type of transaction intended for the property Suggested values are "For sale" or "For rent". You can provide other values as long as they are sufficiently descriptive.

Yes

numberOfBathrooms

Number

The total number of bathrooms in the property. This should be an integer. If there are none, provide "0".

Yes

numberOfBedrooms

Number

The total number of bedrooms in the property. This should be an integer. If there are none, provide "0".

Yes

numberOfParkingSpaces

Number

The total number of parking spaces available in the property. This should be an integer. If there are none, provide "0".

Yes

additionalDetails

String

Additional information about the property that could be beneficial to include in the description. This is a free text area. You can provde any notes you feel are relevant.

area

Number

The total area of the interior space of the property This should be a value representing a square figure such as "2500" or "250" etc.

areaUnit

String

The unit of measurement for the area of the property. Suggeste values are sqft or sqm.

lotSize

String

The size of the land the property is located on. You can provide dimensions such as "10x30" or square figures such as "2500"

lotSizeUnit

String

The unit of measurement for the lot size. Suggested values are acres, sqm, sqft, hectares

length

Number

The approximate number of words to be used in the description. Word limit is 2,000

Character limit is 10,000 You must provide either this field OR the characterCount field

Yes

lengthType

String

"words" or "characters"

Yes

language

String

The language in which the description should be generated. Any ISO 639 language code and ISO 3166-1 Alpha-2 country code i.e. en-US, en-UK, fr-CA

Yes

writingStyle

String

Relaxed, formal, luxury or custom

Yes

tone

String

Ignored unless writing style is "custom"

complexity

String

Ignored unless writing style is "custom"

copyWriter

String

avery, blake, casey, dakota, emerson [all lower case] Recommend using avery or blake for best results. Ratings as of July 23rd 2024: Avery: 4.76 Blake: 4.75 Casey: 3.2 Dakota: 3.1 Emerson: 4

Yes

instructions

Array[ String]

Array of strings containing instructions for the AI to implement when writing. Example input:

["Do not include the zip code when mentioning the address", "Do not mention the listing price"]

Yes

dictionaryRules

Array[rule]

Example input:

[{"type":"substitute term","term":"master bedroom",alternative:"primary bedroom"}] Supported types: "substitute term" and "encourage using the term" Only when substituting a term is the "alternative" field required on the rule.

Yes

communityHighlightsDiscovery

String

Acceptable values are "disabled", "point", "city" or "property_address" 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.

By default auto discovery is disabled, any passed in communityHighlights will be used.

No, defaults to "disabled"

communityHighlights

Array[locations]

If data is provided in this field, automated discovery of community highlights will not occur regardless of the value provided in the communityHighlightsDiscovery field. These should be in an array with objects formatted the same as a Google Places API location results. Further reading: https://developers.google.com/maps/documentation/places/web-service/place-id#places-api Example input: [{"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}]

communityLongitude

Decimal

This is only required when "communityHighlightsDiscovery" is set to "point". In all other cases this value is ignored. Discovered community location data will be based on this as the centre of the search location. Example value: -79.4129782

communityLatitude

Decimal

Response:

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

{
    "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."
}

PreviousWelcome!

Last updated 1 month ago