Upload Listings

List Real Estate Rentals on Marketplace.

Listing properties on Facebook Marketplace is currently a closed beta program.

Agencies who want to list their home rentals on Marketplace can sign up through one of our listing partners.

Getting started

Facebook Product Catalog is used to upload inventory to Facebook Marketplace. In this document, you'll find a step-by-step guide on how to create the catalog, upload it and keep the feed up to date.

1
2
Check the best practices to prepare your feed.
3
Description of the all fields in Real Estate Home listings Catalog.
  • Country specific fields
  • Feed XML example
  • 4

    Step 1: Catalog Setup

    To create a Catalog for Facebook Marketplace, you need a Business Manager account and permission to manage it. If you're new to Facebook business, you may need to set up Business Manager first from https://business.facebook.com/

    Create a Real Estate catalog using the Product Catalog UI
    1. Go to Catalog Manager (https://www.facebook.com/products).
    2. Click [Create Catalog].
    3. Select the catalog type [Real estate - Home Listings] and click Next.
    4. Select Select the business your catalog belongs to and enter a name for your catalog.

    Step 2: Best Practices

    The catalog will contain information for properties such as listing id, name, availability, description, address, bedrooms, bathrooms, images and so on.
    Providing good quality listings is the key success factor for a good experience for Facebook Marketplace users with your partner branding. Poor quality or missing information in the catalog can be the cause of listings being rejected or warnings by the catalog tool.

    Best Practices and requirements

    • Listing file format has to be XML. See below for an example.
    • Send 2+ images per listing. Images should be high quality, and without watermarks or banners.
    • Marketplace only supports residential units for rent currently. (The feed should not contain offices, parking spots, garages, boxes, etc., but only residential houses, apartments, flats, condos, etc.)
    • Remove rich text tags in the description. Marketplace description will not support rich text format(HTML) and will trim the tags automatically.
    • Filter the listings that fall outside of the normal range of the price according to the market. (For example, 1$, less then 100$ or more than 100,000$.)
    • Longitude / Latitude are required to show the listings on the map view.
    • Please provide the full address (including street number and street name). The street number will not appear on the listing.

    Step 3: Feed specs

    Listing Feed

    This is a set of listings uploaded or fetched from your business. A listing item is a single property presented in your website or app. You can have a single feed for all properties in your catalog, or you can have multiple feeds where one feed represents properties in a single country, for a single real estate agency, or for one broker.

    Feed file format: You must provide the listing feed in XML format.

    File FormatDescription

    XML

    Typically generated by automated feed provider systems. A root <listings> XML node encloses a set of <listing> nodes, each representing a home listing. The file must begin with a valid <?xml declaration tag.

    CSV, TSV, JSON

    These formats are not currently supported.

    Our feed parser automatically detects UTF8, UTF16 or UTF32 text-encodings, falling back to LATIN1 if unexpected byte sequences appear.

    Field names must be given exactly as below, in English, while text in field values can be given in any language.

    NameTypeDescription

    home_listing_id

    string

    Required.

    Unique apartment/home/condo level id - most granular id possible.

    home_listing_group_id

    string

    Optional.

    Building or apartment's unique id. Must be unique per group.

    name

    string

    Required.

    Title of the listing.

    description

    string

    Required.

    Short text describing the property. Don't include promotional text or any links. Don't enter text in all capital letters. Use line breaks to format your description (max 5000 characters).

    image

    object

    Required.

    Max 20 items - Max image size: 4MB.

    The first photo will be displayed on Marketplace as the cover image.

    num_beds

    float

    Required.

    The total number of bedrooms. Can be 0 for Studios.

    num_baths

    float

    Required.

    The total number of bathrooms. Must be 1 at minimum.

    num_rooms

    float

    Required.

    The total number of rooms.

    property_type

    string

    Required.

    Type of property. Allowed values: apartment, builder_floor, condo, house, house_in_condominium, house_in_villa, loft, other, penthouse, studio, townhouse.

    listing_type

    string

    Required.

    Type of property. Allowed values: for_rent_by_agent, for_rent_by_owner.

    area_size

    int

    Required.

    The area / space of the floor plan of the listing.

    area_unit

    string

    Required.

    The units (square feet , or square meters) of the floor area value.

    Allowed values:sq_ft, sq_m.

    num_units

    int

    Optional.

    The total number of units in the building (if applicable).

    address

    object

    Required.

    A complete address for the listing that must be resolvable to its location.

    See Address Object Parameters.

    latitude

    float

    Required.

    The latitude of the listing. Example: 37.484100

    latitude

    float

    Required.

    The longitude of the listing. Example: -122.148252

    neighborhood

    string

    Optional but strongly recommended.

    Listing neighborhood. Can have multiple items - Max 20 items.

    furnish_type

    string

    Optional.

    Type of furniture present in the property. Allowed values: furnished, semi-furnished,unfurnished.

    heating_type

    string

    Optional.

    Type of heating present in the property. Allowed values: central,gas,electric,radiator,other,none.

    ac_type

    string

    Optional.

    Type of air conditioning. Allowed values: central, other,none.

    laundry_type

    string

    Optional.

    Type of laundry. Allowed values: in_unit,in_building, other,none.

    parking_type

    string

    Optional.

    Type of parking. Allowed values: garage,street,off-street, other,none.

    pet_policy

    string

    Optional.

    To indicate which pets are allowed in the listing.

    Allowed values: cat, dog, all, none.

    year_built

    string

    Optional.

    YYYY format, 4 digit year.

    Example: 1994.

    price

    string

    Required.

    Currency should follow ISO 4217 currency codes such as 13,999 USD.

    availability

    string

    Required.

    Whether or not the listing is available.

    Allowed value: for_rent.

    url

    string

    Required.

    Link to listing page. Must be a valid URL.

    Example: http://www.realestatecompany.com/example.

    partner_verification

    string

    Optional.

    Whether the partner company has verified the listing.

    Allowed values: verified, none.

    agent_id

    string

    Optional.

    Unique per agent. The id of the agent.

    agent_name

    string

    Optional.

    The listing agent's name.

    Example: John Smith .

    agent_company

    string

    Optional.

    The listing agent's company name. Example: Real Estate Properties .

    agent_phone

    string

    Optional.

    The listing agent's phone number. Must be a valid phone number format, and must include the country code.

    Example: +13603453333, 001(360)345-3333.

    agent_fb_page_id

    string

    Optional.

    The listing agent's Facebook Page ID.

    Address Object Parameters

    NameTypeDescription

    addr1

    string

    Required.

    Street address of the property.

    Example: 675 El Camino Real

    city

    string

    Required.

    City where the property is located.

    Example: Palo Alto

    region

    string

    Required.

    State, county, region or province for the property.

    Example: California

    country

    string

    Required.

    Country of the property.

    Example: United States

    postal_code

    string

    Required unless country doesn't have postal code system.

    Postal or zip-code of the the property.

    Example: 94125, NW1 3FG

    Country specific required fields

    NameTypeDescription

    additional_fees_description

    string

    Required in FR, UK.

    Additional fees for the listing. Any text entered in this field will be rendered in a separated popup dialog, accessible via a "Fees apply" button displayed in the listing details page.

    Max length: 5000 characters.

    energy_rating_eu

    string

    Required in FR.

    The listing's energy rating. A grade and a value should be specified.

    Example: <grade>A</grade><value>123</value>

    co2_emission_rating_eu

    string

    Required in FR.

    The listing's CO2 emissions rating. A grade and a value should be specified.
    Example: <grade>A</grade><value>123</value>

    property_tax

    string

    Required in BR.

    Currency should follow ISO 4217 currency codes such as 1,999 USD.

    condo_fee

    string

    Required in BR.

    Currency should follow ISO 4217 currency codes such as 1,999 USD.

    parking_spaces

    int

    Required in BR.

    Number of parking places available.

    built_up_area_size

    int

    Required in IN.

    Additional area size field for India market to represent built up area size. area_size will represent carpet area size.

    Feed XML example

    <?xml version="1.0" encoding="UTF-8"?>
    <listings>
        <title>example.com Feed</title>
        <link rel="self" href="http://www.example.com"/>
        <listing>
            <home_listing_id>12345678</home_listing_id>
            <name>1 Hacker Way, Menlo Park, CA 94025</name>
            <availability>for_rent</availability>
            <description>An amazing listing</description>
            <address format="simple">
                <component name="addr1">1 Hacker Way</component>
                <component name="city">Menlo Park</component>
                <component name="region">California</component>
                <component name="country">United States</component>
                <component name="postal_code">94025</component>
            </address>
            <latitude>1.11414</latitude>
            <longitude>-1.835003</longitude>
            <neighborhood>Menlo Oaks</neighborhood>
            <image>
                <url>http://example.com/12345678-1.jpg</url>
            </image>
            <image>
                <url>http://example.com/12345678-2.jpg</url>
            </image>
            <image>
                <url>http://example.com/12345678-3.jpg</url>
            </image>
            <listing_type>for_rent_by_agent</listing_type>
            <num_baths>6</num_baths>
            <num_beds>5</num_beds>
            <num_units>1</num_units>
            <price>110000 USD</price>
            <property_type>house</property_type>
            <url>http://www.example.com/link_to_listing</url>
            <year_built>2007</year_built>
        </listing>
    </listings>

    Step 4: Upload Catalog Data Feed

    You can refresh home listing info in the catalog by setting up a recurring (scheduled) feed upload and updating your feed. In Marketplace, we highly recommend to use the Set a Schedule option.

    Set a schedule for your catalog data feed upload

    1. Go to Catalog Manager.
    2. Click Data Sources.
    3. Click Add Data Source.
    4. Click Use Data Feeds and click Next.
    5. Click Set a schedule.
    6. Choose how frequently you want Facebook to check your data feed for updates.
      You can choose Daily, Hourly and Weekly. If you choose Hourly or Weekly as your frequency, you can also specify when your scheduled upload repeats.
    7. Enter the direct URL for your feed. You can use URLs that use http, https, ftp or sftp. Note: The URL should point directly to your data feed file; otherwise, the upload may fail.
    8. (Optional) Enter the username and password for the data feed provider. This is different than the username and password you use to access your Facebook ad account.
    9. Enter a name for your data feed.
    10. Choose the currency type for your data feed. The currency type is used for your data feed if you don't specify it in your data feed file.
    11. Click Next.
    12. Review your data feed file for any errors. If you're missing any required columns in your file, or there are columns that Facebook doesn't recognize, you can map them to the appropriate columns here. Any columns mapped here are saved for future data feed uploads.
    13. Click Next.

    Appendix : Multi language feed upload

    Marketplace Real Estate supports multi language experience. When you add secondary language feed to a catalog, you can create another feed with the second language from that single catalog. The information on the secondary feeds overrides your default language when the relevant audience sees your listings.

    This feature will be applicable only for the specific country partners. Please contact to your Facebook representative to find out possibility in your market.

    1. Create a catalog with a data feed for your default language and country.
    2. Create an XML file only with the listing ID (home_listing_id) and additional fields that required local language overwrite like name, description or additional fields
      * To overwrite information, the home_listing_id must match the ones in your original catalog data feed.
    3. Add the additional information feed from the Catalog manager.

      Add the additional feed from the Catalog manager [Add Home Listing Information] - [Add Language Information]


    4. Double check the 2 data sources within the same catalog.

    Full error reporting / Catalog debugging

    This functionality is in beta.

    There is an API that allows you to download the full report of your catalog errors. Check the question "How can I see the full error list of my catalog?" in our FAQ list for more details.

    Need help?

    You can contact Facebook's Support team any time you have questions.

    Contact us