REST API documentation

Introduction

Floorplanner exposes some of its functionality via an Application Programming Interface (API). This document is a reference for that functionality, and aims to serve as a reference for developers building tools that talk to Floorplanner. For now only Partner accounts can use the API.

Table of Contents

Concepts

Authentication

Many Floorplanner API methods require authentication. All responses are relative to the context of the authenticating user. For example, an attempt to retrieve project information of a private project will fail. HTTP Basic Authentication is the supported authentication scheme. When authenticating via Basic Authentication, use your API key as username and 'x' as password.

RESTful Resources

The Floorplanner API attempts to conform to the design principles of Representational State Transfer (REST). You’ll find that you can simply change the file extension on most any request to get results in the format of your choice. This document notes which formats are available for each method.

Floorplanner presently supports the following data formats: XML, JSON.

HTTP Requests

Methods to retrieve data from the Floorplanner API require a GET request. Methods that submit, change, or destroy data require a POST. A DELETE request is also accepted for methods that destroy data. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct method.

HTTP Headers

Where noted, some API methods will return different results based on HTTP headers sent by the client. Where the same behavior can be controlled by both a parameter and an HTTP header, the parameter will take precedence.

HTTP Status Codes

The Floorplanner API attempts to return appropriate HTTP status codes for every request. Here's what's going on with our various status codes:

  • 200 OK: everything went awesome.
  • 304 Not Modified: there was no new data to return.
  • 400 Bad Request: your request is invalid, and we'll return an error message that tells you why. This is the status code returned if you've exceeded the rate limit (see below).
  • 401 Not Authorized: either you need to provide authentication credentials, or the credentials provided aren't valid.
  • 403 Forbidden: we understand your request, but are refusing to fulfill it. An accompanying error message should explain why.
  • 404 Not Found: either you're requesting an invalid URI or the resource in question doesn't exist (ex: no such user).
  • 500 Internal Server Error: we did something wrong. Please contact us and the Floorplanner team will investigate.
  • 502 Bad Gateway: returned if Floorplanner is down or being upgraded.
  • 503 Service Unavailable: the Floorplanner servers are up, but are overloaded with requests. Try again later.

Error Messages

When the Floorplanner API returns error messages, it does so in your requested format. For example, an error from an XML method might look like this:

<failure status="403" xml:lang="nl">
  <error>You are not allowed to see this project</error>
</failure>

Encoding

The Floorplanner API supports UTF-8 encoding. Please note that angle brackets (”<” and ”>”) are entity-encoded to prevent Cross-Site Scripting attacks for web-embedded consumers of JSON API output. When requesting XML, the response is UTF-8 encoded. Symbols and characters outside of the standard ASCII range may be translated to HTML entities.

Getting Started

There are a couple of things you should know before using the Floorplanner web service API.

  • The API requests have to be sent to your own subdomain. For example: http://mycompany.floorplanner.com/users.xml Only the last part of the URL is specified in the docs (in this case: /users.xml)
  • HTTP and HTTPS are supported
  • If you don't want to work with the user and project IDs of Floorplanner, you can work with your own IDs. You can place these in the external-identifier fields and use them in the same way as you would with FP IDs. NOTE The first character of an external identifier can't be a number.
  • The project methods are normally filtered on a user, for example /users/:uid/projects.xml. However, it's also possible to work without the filtering, like /projects.xml

User Methods

Create user

Creates a user with the given data

URL
/users.format

Supported formats
XML

Supported request methods
POST

Parameters
Required

  • email The email address
  • account-type Contact us to determine the correct account type
  • country-code The Alpha-2 code of a country, see a list here.
  • language The code of a language according to ISO 639-1

Optional

  • external-identifier You can specify a token of your own to identify a user, without using Floorplanner's numerical IDs
  • username A name for the user

Example request

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <email>johndoe@floorplanner.com</email>
  <account-type>pro_s</account-type>
  <country-code>us</country-code>
  <language>en</language>
  <external-identifier>ID5784</external-identifier>
  <username>John Doe Brokers</username>
</user>

Example response

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <country-code>us</country-code>
  <created-at type="datetime">2011-05-10T07:47:18-04:00</created-at>
  <email>johndoe@floorplanner.com</email>
  <external-identifier>ID5784</external-identifier>
  <id type="integer">20695196</id>
  <language>en</language>
  <username>John Doe Brokers</username>
  <account-type>pro_s</account-type>
</user>

List users

Gets a paginated list of the users

URL
/users.format
or
/users.format?page=:page&per_page=:per_page

Supported formats
XML

Supported request methods
GET

Parameters
Optional

  • per_page The number of users in the result.
  • page The results from this page onwards

Example response

<?xml version="1.0" encoding="UTF-8"?>
<users type="array">
  <user>
    <country-code>us</country-code>
    <created-at type="datetime">2011-05-10T07:47:18-04:00</created-at>
    <email>johndoe@floorplanner.com</email>
    <external-identifier nil="true"></external-identifier>
    <id type="integer">20695196</id>
    <username>John Doe Brokers</username>
    <account-type>pro_s</account-type>
  </user>
  <user>
    <country-code>us</country-code>
    <created-at type="datetime">2011-05-10T07:48:18-04:00</created-at>
    <email>nicolangeveld@floorplanner.com</email>
    <external-identifier nil="true"></external-identifier>
    <id type="integer">20695197</id>
    <username>Nico Langeveld Brokers</username>
    <account-type>pro_s</account-type>
  </user>
  ...
</users>

Get user

Gets the data of a user

URL
/users/:uid.format

Supported formats
XML

Supported request methods
GET

Parameters
Required

  • uid the numerical ID or external identifier of a user

Example response

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <country-code>us</country-code>
  <created-at type="datetime">2011-05-10T07:47:18-04:00</created-at>
  <email>johndoe@floorplanner.com</email>
  <external-identifier>ID5784</external-identifier>
  <id type="integer">20695196</id>
  <username>John Doe Brokers</username>
  <account-type>pro_s</account-type>
</user>

Update user

Updates the data of a user

URL
/users/:uid.format

Supported formats
XML

Supported request methods
PUT

Parameters
Required

  • uid The numerical ID or external identifier of a user

Optional

  • country-code The Alpha-2 code of a country, see a list here.
  • email The new email address
  • external-identifier The new external identifier
  • password The new password
  • password-confirmation The confirmation of the new password
  • username The new user name

Example request

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <email>nicolangeveld@floorplanner.com</email>
</user>

Example response
See the response of Get user.

Delete user

Deletes the user

URL
/users/:uid.format

Supported formats
XML

Supported request methods
DELETE

Parameters
Required

  • uid The numerical ID or external identifier of a user

Returns
Only a HTTP status header

Get token

Retrieve a user token

URL
/users/:uid/token.format

Supported formats
XML, No format

Supported request methods
GET

Parameters
Required

  • uid The numerical ID or external identifier of a user

Returns
For XML, a XML object with current-token as the user token. When no format is specified the body has the user token.

Project Methods

Create project

Creates a new project.

URL
/projects.format

Supported formats
XML

Supported request methods
POST

Parameters
Optional

  • name The name of the project
  • description The description
  • external-identifier You can specify a token of your own to identify a project, without using Floorplanner's numerical IDs
  • public Make the project public or private

Example request
It's also possible to create a new project by posting a whole FML file.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <name>My new house</name>
  <description>This is my first floor plan</description>
  <external-identifier>ID3344</external-identifier>
</project>

Example response
See response of Get project.

Create project with image

Creates a new project with a background image

URL
/projects.format

Supported formats
XML

Supported request methods
POST

Parameters
Optional

  • name The name of the project
  • description The description
  • external-identifier You can specify a token of your own to identify a project, without using Floorplanner's numerical IDs
  • public Make the project public or private
  • drawing-url A url for a background image (supported formats: jpg,png,gif,swf)

Example request
It's also possible to create a new project by posting a whole FML file.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <name>Test project</name>
  <floors type="array">
    <floor>
      <name>Test floor</name>
      <drawing-url>http://www.your-site.com/drawing.jpg</drawing-url>
    </floor>
  </floors>
</project>

Example response
See response of Get project.

Create project with MagicPlan XML

Creates a new project from the data of a MagicPlan plan, using MagicPlan XML data.

URL
/magicplan/import

Supported formats
XML

Supported request methods
POST & GET

Parameters
None

Request body
The MagicPlan XML should be send in the request body, not as a parameter.

Example response
See response of Get project.

Get project

Gets the project of a user.

URL
/projects/:pid.format

Supported formats
XML

Supported request methods
GET

Parameters
Required

  • pid The numerical ID of external identifier of a project

Example response
The project has more tags than shown here, but these are the most important ones.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <created-at type="datetime">2010-04-07T14:10:06-04:00</created-at>
  <description>This is my first floor plan</description>
  <external-identifier>ID3344</external-identifier>
  <id type="integer">20456637</id>
  <name>My new house</name>
  <public type="boolean">true</public>
  <updated-at type="datetime">2011-06-23T05:04:09-04:00</updated-at>
  <user-id type="integer">19342334</user-id>
  <floors type="array">
    <floor>
      <id type="integer">21459797</id>
      <name>First floor</name>
      <level type="integer">0</level>
      <height type="decimal">2.8</height>
      <created-at>2011-03-14 09:19:56 -0400</created-at>
      <updated-at>2011-06-23 00:23:43 -0400</updated-at>
      <designs type="array">
        <design>
          <id type="integer">22530293</id>
          <name>Studio</name>
          <design-type>save</design-type>
          <thumb-2d-url></thumb-2d-url>
          <created-at>2011-03-14 09:24:54 -0400</created-at>
          <updated-at>2011-04-01 06:14:36 -0400</updated-at>
          <project-id>2</project-id>
          <floor-id>21459797</floor-id>
        </design>
      </designs>
    </floor>
  </floors>
</project>

List projects

Gets a paginated list of the projects of a user.

URL
/projects.format
or
/projects.format?page=:page&per_page=:per_page&compact=:compact&q=:q

Supported formats
XML

Supported request methods
GET

Parameters
Optional

  • per_page The number of projects in the result.
  • page The results from this page onwards
  • compact A boolean to only get compact project information (no floors, no designs etc)
  • q A query to search for projects (name, description, tags)

Example response
This is only a high level view.

<?xml version="1.0" encoding="UTF-8"?>
<projects type="array">
  <project>
    ..
  </project>
  <project>
    ..
  </project>
</projects>

Search projects

List projects with designs

Gets a list of projects per user which have a design.

URL
/users/:uid/projects_with_designs.format
or
/users/:uid/projects_with_designs.format?q=:q

Supported formats
XML

Supported request methods
GET

Parameters
Optional

  • q A query to search for projects external_identifier (q%)

Example response
This is only a high level view.

<?xml version="1.0" encoding="UTF-8"?>
<projects type="array">
  <project>
    ..
  </project>
  <project>
    ..
  </project>
</projects>

Update project

Updates one or more properties of a project

URL
/projects/:pid.format

Supported formats
XML

Supported request methods
PUT

Parameters
Required

  • pid The numerical ID of external identifier of a project

Optional

  • name The name of the project
  • description The description
  • external-identifier You can specify a token of your own to identify a project, without using Floorplanner's numerical IDs
  • public Make the project public or private

Example request

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <description>Stationsplein 45a, Rotterdam, Netherlands</description>
</project>

Example response
See the response of Get project

Delete project

Deletes a project of a user

URL
/projects/:pid.format

Supported formats
XML

Supported request methods
DELETE

Parameters
Required

  • pid The numerical ID or external identifier of a project

Returns
Only a HTTP status header

Export project (as FML)

Exports a full project, complete with floors and full designs, of a user in the FML format.

URL
/projects/:pid/export.format

Formats
XML

Supported request methods
GET

Parameters
Required

  • pid The numerical ID or external identifier of a project

Returns
The full project in FML format.

Export project (as image)

Exports a project of a user to variety of formats. The linked ZIP archive will contain files of all the designs in a project, named with [ID].ext (where ext depends on type param.). So if the project contains 2 designs with IDs of 234 and 567, and type is image/png, the ZIP will contain 234.png and 567.png

Allowed types are:

  • image/jpeg
  • image/png
  • image/svg+xml
  • application/pdf
  • application/vnd.google-earth.kmz
  • application/sla

URL
/projects/:pid/render

Supported request methods
POST

Parameters
Required

  • pid The numerical ID or external identifier of a project
  • resolution[width] The width of the image(s) in pixels (or millimeters for PDF)
  • resolution[height] The height of the image(s) in pixels (or millimeters for PDF)
  • callback After all design images have been exported, the callback URL will receive a POST request containing XML result message OR send_to - result will be sent to given email address

Optional

  • type MIME type of requested export format
  • paper_scale Number between 0.002 and 0.02 (PDF only, see design export)
  • scaling if set to 'constant', all designs will be scaled by the same ratio
  • scalebar set to 1 or “true” to include a scale bar in the output image
  • black_white Boolean value (true/false) of whether the output should be in grayscale

Returns
None (HTTP status code)

Note:
Export result URL expires in 3 days.

Example request

<export xmlns="http://floorplanner.com/export/request">
  <resolution>
    <width>400</width>
    <height>300</height>
  </resolution>
  <callback>http://yourapp.com/handle_fp_export/</callback>
</export>

Example callback request

<result xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://floorplanner.com/export/result">
  <link xlink:href="http://example.com/project.zip" type="application/zip"/>
</result>

Copy project

Copies a project of a user within its account.

URL
/projects/:pid/copy.format

Supported formats
XML

Supported request methods
POST

Parameters
Required

  • pid The numerical ID or external identifier of a project

Returns
The copied project. See the response of Get project.

Deliver project

Copies a project of a user to another user.

URL
/projects/:pid/deliver.format
or
/projects/:pid/deliver.format?disable_email=1

Supported formats
XML

Supported request methods
POST

Parameters
Required

  • pid The numerical ID of external identifier of a project
  • email The Floorplanner user with this email address will get a copy of the project
  • disable_email Normally the user will get a notification email. This can be turned off by this parameter

Returns
Only a header.

Example request:

<?xml version="1.0" encoding="UTF-8"?>
<email>johndoe@floorplanner.com</email>

Collaborate on project

Gives another user edit rights to a project of a user.

URL
/projects/:pid/collaborate.format

Supported formats
XML

Supported request methods
POST

Parameters
Required

  • pid The numerical ID or external identifier of a project
  • email The Floorplanner user with this email address will be able to collaborate on the project

Returns
The user object of the collaborator. See the response of Get user.

Example request

<?xml version="1.0" encoding="UTF-8"?>
<email>johndoe@floorplanner.com</email>

Publish project

A project is published to make it public. The result is an interactive floor plan that can be zoomed, panned and decorated by visitors.

URL
/projects/:pid/configuration.format
Note: make sure you use the correct subdomain

Supported formats
XML

Supported request methods
POST

Parameters
Required

  • pid The numerical ID or external identifier of a project
  • path The part of the URL that comes after the pl.an/ domain: http://pl.an/:path

Optional

  • style-id The numerical ID of a style
  • show-furniture-and-texture-libraries A boolean to indicate if visitors are allowed to decorate the plan or not
  • show-measurement-system A boolean to show or hide the meter/feet toggle in the bottom left corner
  • show-3d A boolean to give visitors access to the 3D view of a plan
  • show-dimensions A boolean to show or hide the automatic wall dimensions
  • show-custom-dimensions A boolean to show or hide the hand draw dimension lines
  • allow-print A boolean to control printing
  • allow-save-by-mail A boolean to indicate if visitors are allowed to share the plan (via email, Twitter or Facebook)
  • show-sidebar A boolean to show or hide the sidebar
  • cc-addresses A list of comma separated email addresses
  • allow-cc-addresses A boolean to indicate if the email addresses in the cc-addresses list should get a notification email when a visitor saves a design
  • receive_bcc A boolean to indicate if the owner of the project should get a notification email when a visitor saves a design
  • element-categories A list of comma separated numerical IDs of element categories. The elements (furniture items) of these categories are shown in the furniture library.
  • init-module A string which shows the active sidebar tab when loading the project. (options: details, media, location, share, assets, tutorial)
  • hide-scale-bar A boolean to indicate if the scale bar should not be shown

Returns
The publish configuration of a project

Example request

<?xml version="1.0" encoding="UTF-8"?>
<publish-configuration>
  <path>stationsplein-45a</path>
  <style-id>244</style-id>
  <show-measurement-system>1</show-measurement-system>
  <allow-save-by-mail>1</allow-save-by-mail>
</publish-configuration>

Unpublish project

A published project is public. If you want to make a project private or if you want to delete it you have to 'unpublish' it first.

URL
/projects/:pid/configuration.format

Supported formats
XML

Supported request methods
DELETE

Parameters
Required

  • pid The numerical ID or the external identifier of a project

Returns
See the response of Get project.

Design Methods

Export design (as image)

Exports a design to variety of formats. Specify the format in 'type' parameter, allowed values are:

  • image/jpeg
  • image/png
  • image/svg+xml
  • application/pdf
  • application/vnd.google-earth.kmz
  • application/sla

URL
/projects/:pid/floors/:fid/designs/:did/export.format OR /designs/:did/export

Supported formats
XML

Supported request methods
POST

Parameters
Required

  • pid The numerical ID of a project
  • fid The numerical ID of a floor
  • did The numerical ID of a design
  • resolution[width] The width of the image(s) in pixels (or millimeters for PDF)
  • resolution[height] The height of the image(s) in pixels (or millimeters for PDF)
  • black_white Boolean value (true/false) of whether the output should be in grayscale
  • callback After all design image has been exported, the callback URL will receive a POST request containing XML result message

Optional

  • type Export format, default image/jpeg
  • paper_scale Number between 0.002 and 0.02 (PDF only)

Returns
None (HTTP status code)

Note:
Export result URL expires in 3 days. PDF export also allows you to specify paper_scale parameter, a floating point number specifying physical scale, e.g. for 1:100 scale, you would use 0.01, for 1:50 it would be 0.02, etc.

Example request

<export xmlns="http://floorplanner.com/export/request">
  <resolution>
    <width>400</width>
    <height>300</height>
  </resolution>
  <callback>http://yourapp.com/handle_fp_export/</callback>
</export>

OR (with CURL)

curl -v -u api_key:x http://floorplanner.com/designs/12345/export -XPOST -F resolution[width]=400 -F resolution[height]=300 -F callback=http://domain.com/receiver

Callback request

<result xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://floorplanner.com/export/result">
  <link xlink:href="https://example.com/image.png" type="image/png"/>
  <bounds units="m" top="-0.015" right="13.371" bottom="10.492" left="-0.638"/>
</result>

Render design (3D)

Renders a 3D image of the design.

URL
/projects/:pid/floors/:fid/designs/:did/export_render

Supported formats
XML, JSON

Supported request methods
POST

Parameters
Required

  • pid The numerical ID of a project
  • fid The numerical ID of a floor
  • did The numerical ID of a design
  • width The width of the image(s) in pixels
  • height The height of the image(s) in pixels
  • angle One 'SW', 'SE', 'NW', 'NE', 'TD' strings corresponding to the south-west, south-east, north-west, north-east, top-down views
  • wall_tops Color of the top part of walls as hexadecimal string, eg. #FF0000
  • callback After all design image has been exported, the callback URL will receive a POST request containing XML result message

Returns
None (HTTP status code)

Example request

<export xmlns="http://floorplanner.com/export/render">
   <resolution>
    <width>400</width>
    <height>300</height>
   </resolution>
   <angle>SW</angle>
   <wall-tops>#000000</wall-tops>
   <callback>http://yourapp.com/handle_fp_export/</callback>
</export>

Gallery methods

Featured gallery

Get the list of featured design from the gallery.

URL
/gallery/featured.format

Supported formats
XML, JSON, RSS

Supported request methods
GET

Parameters

Example response

<?xml version="1.0" encoding="UTF-8"?>
<designs type="array">
  <design>
    <id>24854471</id>
    <name>small house 2 Bed</name>
    <design-type>save</design-type>
    <thumb-2d-url>http://data.floorplanner.com/thumbs/24854471.png</thumb-2d-url>
    <created-at>2012-01-02 12:39:45 -0500</created-at>
    <updated-at>2012-01-02 15:11:54 -0500</updated-at>
    <project-id>22311821</project-id>
    <floor-id>23785546</floor-id>
  </design>
</designs>

Fresh gallery

Get the list of fresh design from the gallery.

URL
/gallery/fresh.format

Supported formats
XML, JSON, RSS

Supported request methods
GET

Parameters

Example response

<?xml version="1.0" encoding="UTF-8"?>
<designs type="array">
  <design>
    <id>24859876</id>
    <name>alkemadelaan35</name>
    <design-type>save</design-type>
    <thumb-2d-url>http://data.floorplanner.com/thumbs/24859876.png</thumb-2d-url>
    <created-at>2012-01-03 03:53:49 -0500</created-at>
    <updated-at>2012-01-03 04:04:07 -0500</updated-at>
    <project-id>22333167</project-id>
    <floor-id>23821076</floor-id>
    </design>
</designs>