BoxBrownie.com API v2.0 Docs

Overview

360° Virtual Tours are a great way to show off a property by utlising 360° panoramas to create an interactive virtual walk-through of a property. Our 360° Virtual Tours support properties of any size, and can optionally include floor plans, alternate versions of panoramas, and a custom agency logo.

Create a 360° Virtual Tour

POST /api/v2/job/createVirtualTour

Endpoint: https://www.boxbrownie.com/api/v2/job/createVirtualTour
HTTP Method: POST
Requires Authentication? Yes
Required Parameters: xml
Optional Parameters: (string) responseFormat [json|xml]

To create a 360° Virtual Tour, we require you to send us an XML payload that contains a job title and a list of rooms with 360° panoramas supplied as file URLs. Optionally, you may also provide file URLs for any floor plans you wish to include, a file URL for an agency logo, and file URLs for any alternate versions of a 360° panorama.

Your job XML should start with a job title.

<jobTitle>	String	Required	Max 1 Occurence	The title for the job. 100 characters max

Your XML will need to provide an occurrence of <rooms>.

<rooms>		Required	Max 1 Occurence	Contains one or more `<room>` elements

Then, for each primary image that you want to include in your 360° Virtual Tour, your XML should contain an occurence of <room>. Each <room> must at minumum contain a <roomTitle> and a <fileURL>. Your XML must contain at least one <room> element.

<room>		Required	Multiple Allowed	Represents one room in a 360° Virtual Tour. Contains XML for a room title, any images (primary and alternate images) and any other optional data
<roomTitle>	String	Required	Max 1 Occurence	The title of the room. This title will appear in the completed 360° Virtual Tour.
<fileURL>	String	Required	Max 1 Occurence	A file URL for a 360° panorama. This image will serve as the primary image for the room
<isStartingRoom>	Boolean	Optional	Max 1 Occurence	Providing a value of `true` will designate this room as the starting room when first loading the 360° Virtual Tour. Only one `<room>` can be designated as the starting room.

Within the <room> element, you may optionally provide one or more alternate 360° panoramas as <fileURL> elements inside a <roomStyles> block. This can be useful if you wanted to show variations of the primary panorama, such as a virtually staged or unstaged version. Users will be able to easily switch between the primary panorama and any alternate panoramas.

<roomStyles>		Optional	Max 1 Occurence	Contains one or more `<fileURL>` elements
<fileURL>	String	Required	Multiple Allowed	A file URL for a 360° panorama. This image will serve as an alternate version of the primary image for the room

Optionally, you may also provide a <floorPlans> element as a child of the top level <job> element that contains one or more <fileURL> elements. Each <fileURL> should point to an image file, and will be displayed in the completed 360° Virtual Tour.

<floorPlans>		Optional	Max 1 Occurence	Contains one or more `<fileURL>` elements
<fileURL>	String	Required	Multiple Allowed	A file URL for a floor plan image. This image will be displayed on the completed 360° Virtual Tour

Optionally, you may also provide a <agencyLogo> element as a child of the top level <job> element that contains one <fileURL> element. This <fileURL> should point to an image file, and will be displayed in the completed 360° Virtual Tour.

<agencyLogo>		Optional	Max 1 Occurence	Contains one `<fileURL>` element
<fileURL>	String	Required	Max 1 Occurence	A file URL for an agency logo image. This image will be displayed on the completed 360° Virtual Tour

Optionally, you may also provide a <comments> element as a child of the top level <job> element that contains a string describing any special/additional instructions.

<comments>	String	Optional	Max 1 Occurence	Any additional/special instructions for the 360° Virtual Tour

Example XML

Below, you can see an example XML payload. This example defines 2 <room> elements, each with some alternate panoramas, some floor plan images, and an agency logo. If this were a real job, you could expect to receive a 360° Virtual Tour with 2 rooms when completed.

<job>
    <jobTitle>My Virtual Tour</jobTitle>
    <rooms>
        <room>
            <roomTitle>Main Bedroom</roomTitle>
            <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured02.png</fileURL>
            <isStartingRoom>1</isStartingRoom>
            <roomStyles>
                <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured03.png</fileURL>
                <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured04.png</fileURL>
            </roomStyles>
        </room>
        <room>
            <roomTitle>Hallway</roomTitle>
            <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured01.png</fileURL>
        </room>
    </rooms>
    <floorPlans>
        <fileURL>https://boxbrownie-virtual-tours.b-cdn.net/7bbda25afdbbf7a474ae88d9d9d2b5577afc3396/floorPlan/6yg7abhvcdbnim8vt8er8ou6fvkentq98grrxb51.jpg</fileURL>
        <fileURL>https://boxbrownie-virtual-tours.b-cdn.net/7bbda25afdbbf7a474ae88d9d9d2b5577afc3396/floorPlan/gxn8vzps72pm0pc3ngpr4s7vfg5thcpqdv7w6m5o.jpg</fileURL>
    </floorPlans>
    <agencyLogo>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/trusted/ljHooker.png</fileURL>
    </agencyLogo>
    <comments>Don't forget my alternate styles!</comments>
</job>

Example Response

Below, you can see an example response for the above example API Request.

{
  "success": "1",
  "job": {
    "jobId": "a994b2d08216336bd6548c11cc0ff90eef66acca",
    "jobTitle": "My Virtual Tour",
    "jobReference": "T737621569434",
    "jobStatus": "Pending",
    "jobDateSubmitted": "2024-03-15 14:07:30",
    "jobCost": "20.00",
    "jobCostCurrency": "AUD"
  }
}

<?xml version="1.0"?>
<response>
    <success>1</success>
    <job>
        <jobId>a994b2d08216336bd6548c11cc0ff90eef66acca</jobId>
        <jobTitle>My Virtual Tour</jobTitle>
        <jobReference>T737621569434</jobReference>
        <jobStatus>Pending</jobStatus>
        <jobDateSubmitted>2024-03-15 14:07:30</jobDateSubmitted>
        <jobCost>20.00</jobCost>
        <jobCostCurrency>AUD</jobCostCurrency>
    </job>
</response>

Simulate a 360° Virtual Tour

POST /api/v2/job/simulateVirtualTour

Endpoint: https://www.boxbrownie.com/api/v2/job/simulateVirtualTour
HTTP Method: POST
Requires Authentication? Yes
Required Parameters: xml
Optional Parameters: (string) responseFormat [json|xml]

The BoxBrownie.com API allows you to simulate the creation of a 360° Virtual Tour in order to check for any errors in the XML payload of a job submission by using this endpoint. Additionally, this endpoint will return the expected job credit cost for the XML payload.

This endpoint accepts the same XML that you would use with the Create a 360° Virtual Tour endpoint.

Note: Using this endpoint will not create any jobs in your account, and will not charge your BoxBrownie.com account.

Note: Estimated credit cost does not take into account any free trials associated with your BoxBrownie.com account.

Example Response

Below, you can see an example response when supplying job XML to this endpoint.

{
  "success": "1",
  "jobCost": "20.00",
  "jobCostCurrency": "AUD",
  "xmlIsValid": "1"
}

<?xml version="1.0"?>
<response>
    <success>1</success>
    <jobCost>20.00</jobCost>
    <jobCostCurrency>AUD</jobCostCurrency>
    <xmlIsValid>1</xmlIsValid>
</response>

Retrieve a 360° Virtual Tour

GET /api/v2/job/{jobReference}

Endpoint: https://www.boxbrownie.com/api/v2/job/{jobReference}
HTTP Method: GET
Requires Authentication? Yes
Required Parameters: jobReference
Optional Parameters: (string) responseFormat [json|xml]

You may retrieve details about any job in your BoxBrownie.com account by supplying the reference number of the job jobReference.

Note: If the 360° Virtual Tour you are retrieving is completed, a public URL and a shareable QR Code will be returned in the response.

Example Response

{
  "job": {
    "jobId": "a994b2d08216336bd6548c11cc0ff90eef66acca",
    "jobTitle": "My Virtual Tour",
    "jobReference": "T737621569434",
    "jobStatus": "Completed",
    "jobDateSubmitted": "2024-03-15 14:07:30",
    "jobCost": "20.00",
    "jobCostCurrency": "AUD",
    "jobDateCompleted": "2024-03-15 11:54:29",
    "output": {
      "virtualTourURL": "https://www.boxbrownie.com/360/?c=a994b2d08216336bd6548c11cc0ff90eef66acca",
      "virtualTourQRCode": "data:image/png;base64,iVBORw0KGgo..."
    }
  }
}

<?xml version="1.0"?>
<response>
    <job>
        <jobId>a994b2d08216336bd6548c11cc0ff90eef66acca</jobId>
        <jobTitle>My Virtual Tour</jobTitle>
        <jobReference>T737621569434</jobReference>
        <jobStatus>Completed</jobStatus>
        <jobDateSubmitted>2024-03-15 14:07:30</jobDateSubmitted>
        <jobCost>20.00</jobCost>
        <jobCostCurrency>AUD</jobCostCurrency>
        <jobDateCompleted>2024-03-15 11:54:29</jobDateCompleted>
        <output>
            <virtualTourURL>https://www.boxbrownie.com/360/?c=a994b2d08216336bd6548c11cc0ff90eef66acca</virtualTourURL>
            <virtualTourQRCode>data:image/png;base64,iVBORw0KGgo...</virtualTourQRCode>
        </output>
    </job>
</response>

Rework a 360° Virtual Tour

POST /api/v2/job/reworkVirtualTour

Endpoint: https://www.boxbrownie.com/api/v2/job/reworkVirtualTour
HTTP Method: POST
Requires Authentication? Yes
Required Parameters: xml
Optional Parameters: (string) responseFormat [json|xml]

After a 360° Virtual Tour has been completed, you will have the ability to submit a rework request. Similarly to creating a new job, you will be required to supply an XML payload with instructions about what you want changed.

You must supply either a <jobId> or a <jobReference> and at a <reworkComment> that contains a string value describing the changes you require.

Note: 360° Virtual Tours can only be reworked if it has a jobStatus of Completed, and if there are no existing active reworks for the job.

Example XML

Below, you can see an example XML payload.

<job>
    <jobId>a994b2d08216336bd6548c11cc0ff90eef66acca</jobId>
    <reworkComment>Please change navigation icons to blue</reworkComment>
</job>

Example Response

{
  "success": "1",
  "reworkId": "ebc28c0d578d512b50c1cab9ed638f16fbca6a20"
}

<?xml version="1.0"?>
<response>
    <success>1</success>
    <reworkId>ebc28c0d578d512b50c1cab9ed638f16fbca6a20</reworkId>
</response>

Topics

360° Virtual Tours

Overview

Create a 360° Virtual Tour

Example XML

Example Response

Simulate a 360° Virtual Tour

Example Response

Retrieve a 360° Virtual Tour

Example Response

Rework a 360° Virtual Tour

Example XML

Example Response