Introduction

Floorplanner exposes some of its functionality through an Application Programming Interface (API). This document is a reference for that functionality and aims to serve as a guide 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.

Parameter Required Value
username yes [Your API key]
password yes x

Errors

When the Floorplanner API returns error messages, it does so in your requested format. For example, an error from an API call through XML 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)
  • Both 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 API calls are scoped by user, for example /users/:uid/projects.xml. However, it’s also possible to work without scoping by accessing the resource directly instead of through the /users/:uid namespace /projects.xml

API Endpoints

Users

Create

Creates a user with the given data.

POST /users.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
email yes Users’ email address
account-type yes Contact us to determine the correct account type
country-code yes The ISO 3166-1 Alpha-2 country code
language yes The language code of a country following ISO 639-1
external-identifier no You can specify a token of your own to identify a user, without using Floorplanner’s numerical IDs
username no A username for the user
password no A password for the user
password-confirmation yes if password is specified Confirmation of the password

<?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>
HTTP 200
<?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>

Index

Get a (paginated) list of users.

GET /users.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
per_page no The amount of results displayed per page
page no A number that indicates the page you are on (and offset using per_page * (page - 1))
HTTP 200
<?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>
  <!-- ... snipped ... -->
</users>

Show

Get specific users’ attributes.

GET /users/:id.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
:id yes The numerical or external ID of a user
HTTP 200
<?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

Updates the attributes of the user.

PUT /users/:id.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
:id yes The numerical or external ID of a user
country-code no The ISO 3166-1 Alpha-2 country code
email no The new email address
external-identifier no The new external identifier
username no The new username
password no The new password
password-confirmation yes if password is specified The confirmation of the new password

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <email>nicolangeveld@floorplanner.com</email>
</user>
HTTP 200
<?xml version="1.0" encoding="UTF-8"?>
<user>
  <country-code>us</country-code>
  <created-at type="datetime">209-05-10T09:32:23-04:20</created-at>
  <email>nicolangeveld@floorplanner.com</email>
  <external-identifier>ID213567</external-identifier>
  <id type="integer">234567</id>
  <username>Nico Langeveld</username>
  <account-type>pro_s</account-type>
</user>

Destroy

Deletes the user.

DELETE /users/:id.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
:id yes The numerical or external ID of a user
HTTP 200

Token

Retrieve a user token.

DELETE /users/:id/token.:format
Parameter Required Value
:id yes The numerical or external ID of a user
:format no xml is the only supported format at the moment, if omitted, the response body will contain the token.
HTTP 200

Response using xml format, also fetches other user information.

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <country-code>NL</country-code>
  <created-at type="datetime">2009-05-23T14:05:56-04:00</created-at>
  <email>sidney@floorplanner.com</email>
  <external-identifier nil="true"/>
  <id type="integer">18512526</id>
  <measurement-system>METRIC</measurement-system>
  <profile nil="true"/>
  <username/>
  <current-token>cd868133e0fdab5bb5352f51bc1e715d</current-token>
  <account-type>admin</account-type>
  <url/>
</user>

Response using plain format. (e.g. no :format specified)

cd868133e0fdab5bb5352f51bc1e715d

Projects

Create

Creates a new project.

POST /projects.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
name no The name of the project
description no The description of the project
external-identifier no You can specify a token of your own to identify a project, without using Floorplanner’s numerical IDs
public no Make the project public or private
drawing-url no A URL for the background image (supports: .jpg, .png, .gif, .swf)

<?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>
HTTP 200
<?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>

Gets a paginated list of the projects of a user.

GET /projects.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
per_page no The amount of results displayed per page
page no A number that indicates the page you are on (and offset using per_page * (page - 1))
compact no Either true or false, only get compact project information (no floors, no designs etc…).
q no A query to search for projects (name, description and tags will be searched).
HTTP 200
<?xml version="1.0" encoding="UTF-8"?>
<projects type="array">
  <project>
    <!-- ... snipped ... -->
  </project>
  <project>
    <!-- ... snipped ... -->
  </project>
</projects>

Index projects with designs

Get a list of a user’s projects that contain a design.

GET /users/:user_id/projects.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
:user_id yes The user’s ID
q no A query to search projects external ID (using: q%)
HTTP 200
<?xml version="1.0" encoding="UTF-8"?>
<projects type="array">
  <project>
    <!-- ... snipped ... -->
  </project>
  <project>
    <!-- ... snipped ... -->
  </project>
</projects>

Show

Get the project of a user.

GET /projects/:id.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
:id yes The numerical ID or external ID of a project
HTTP 200
<?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>

Update

Updates one or more attributes of a project.

PUT /projects/:id.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
:id yes The numerical ID or external ID of a project
name no The name of the project
description no The description of the project
external-identifier no You can specify a token of your own to identify a project, without using Floorplanner’s numerical IDs
public no Make the project public or private

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <description>Stationsplein 45a, Rotterdam, Netherlands</description>
</project>
HTTP 200
<?xml version="1.0" encoding="UTF-8"?>
<project>
  <created-at type="datetime">2010-04-07T14:10:06-04:00</created-at>
  <description>Stationsplein 45a, Rotterdam, Netherlands</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>

Destroy

Deletes a project.

DELETE /projects/:id.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
:id yes The numerical ID or external ID of a project
HTTP 200

Export (as FML)

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

GET /projects/:id/export.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
:id yes The numerical ID or external ID of a project
HTTP 200
<?xml version="1.0" encoding="UTF-8"?>
<project>
  ...
  <floors type="array">
    <floor>
      ...
      <designs type="array">
        <design>
          ...
        </design>
      </designs>
    </floor>
  </floors>
</project>

Export (as image)

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

Note: the export URL will expire within 3 days.

POST /projects/:id/render
Parameter Required Value
:id yes The numerical ID or external ID of a project
resolution[width] yes The width of the image(s) in pixels (or millimeters for PDF)
resolution[height] yes The height of the image(s) in pixels (or millimeters for PDF)
callback yes unless send_to is specified After all design images have been exported, the callback URL will receive a POST request containing XML result message.
send_to yes unless callback is specified result will be sent to given email address
type no MIME type of requested export format
paper_scale no Number between 0.002 and 0.02 (PDF only, see design export)
scaling no if set to constant, all designs will be scaled by the same ratio
scalebar no set to either 1 or true to include a scale bar in the output image
black_white no Either true or false, wether the output should be in grayscale

<?xml version="1.0" encoding="UTF-8"?>
<export xmlns="http://floorplanner.com/export/request">
  <resolution>
    <width>400</width>
    <height>300</height>
  </resolution>
  <callback>http://yourapp.com/handle_fp_export/</callback>
</export>
HTTP 200

The following request will be made from our servers to the callback url, the request body will consist of XML data containing the URL to your exported project files. The request will only be made if a callback is specified.

POST callback
<?xml version="1.0" encoding="UTF-8"?>
<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

Copies a project of a user within its account.

POST /projects/:id/copy.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
:id yes The numerical ID or external ID of a project
HTTP 200
<?xml version="1.0" encoding="UTF-8"?>
<project>
  <created-at type="datetime">2010-04-07T14:10:06-04:00</created-at>
  <description>Stationsplein 45a, Rotterdam, Netherlands</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>

Deliver (copy to other user)

Copies a project of a user to another user.

POST /projects/:id/deliver.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
:id yes The numerical ID or external ID of a project
email yes The Floorplanner user with this email address will get a copy of the project
disable_email yes Normally the user will get a notification email. This can be turned off by setting this parameter to 1

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

Collaborate

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

POST /projects/:id/collaborate.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
:id yes The numerical ID or external ID of a project
email yes The Floorplanner user with this email address will get a copy of the project

<?xml version="1.0" encoding="UTF-8"?>
<email>johndoe@floorplanner.com</email>
HTTP 200
<?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>

Publish

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

POST /projects/:id/configuration.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
:id yes The numerical ID or external ID of a project
path yes The part of the URL that comes after the pl.an/ domain: pl.an/:path
style-id no The numerical ID of a style
show-furniture-and-texture-libraries no Either true or false, indicate if visitors are allowed to decorate the plan or not
show-measurement-system no Either true or false, show or hide the meter/feet toggle in the bottom left corner
show-3d no Either true or false, give visitors access to the 3D view of a plan
show-dimensions no Either true or false, show or hide the automatic wall dimensions
show-custom-dimensions no Either true or false, show or hide the hand draw dimension lines
allow-print no Either true or false, control printing
allow-save-by-mail no Either true or false, indicate if visitors are allowed to share the plan (via email, Twitter or Facebook)
show-sidebar no Either true or false, show or hide the sidebar
cc-addresses no A list of comma separated email addresses
allow-cc-addresses no Either true or false, indicate if the email addresses in the cc-addresses list should get a notification email when a visitor saves a design
receive_bcc no Either true or false, indicate if the owner of the project should get a notification email when a visitor saves a design
element-categories no 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 no A string which shows the active sidebar tab when loading the project. (options: details, media, location, share, assets, tutorial)
hide-scale-bar no Either true or false, indicate if the scale bar should not be shown

<?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>
HTTP 200
<?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>
  <!-- ... snipped ... -->
</publish-configuration>

Unpublish

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.

DELETE /projects/:id/configuration.:format
Parameter Required Value
:format yes xml is the only supported format at the moment
:id yes The numerical ID or external ID of a project
HTTP 200

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>

Designs

Export (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

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.

Note: the export URL will expire within 3 days.

POST /designs/:id/export
Parameter Required Value
:id yes The numerical ID of a design
resolution[width] yes The width of the image(s) in pixels (or millimeters for PDF)
resolution[height] yes The height of the image(s) in pixels (or millimeters for PDF)
callback yes After all design image has been exported, the callback URL will receive a POST request containing XML result message
type no Export format (see above for a list), default image/jpeg
paper_scale no Number between 0.002 and 0.02 (PDF only)
black_white no Either true or false, wether the output should be in grayscale

<?xml version="1.0" encoding="UTF-8"?>
<export xmlns="http://floorplanner.com/export/request">
  <resolution>
    <width>400</width>
    <height>300</height>
  </resolution>
  <callback>http://yourapp.com/handle_fp_export/</callback>
</export>
HTTP 200

The following request will be made from our servers to the callback url, the request body will consist of XML data containing the URL to your exported project files.

POST callback
<?xml version="1.0" encoding="UTF-8"?>
<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 (3D)

POST /projects/:pid/floors/:fid/designs/:id/export_render
Parameter Required Value
:pid yes The numerical ID of a project
:fid yes The numerical ID of a floor
:id yes The numerical ID of a design
width yes The width of the image(s) in pixels
height yes The height of the image(s) in pixels
angle yes One SW, SE, NW, NE, TD strings corresponding to the south-west, south-east, north-west, north-east, top-down views
wall_tops yes Color of the top part of walls as hexadecimal string, e.g. #FF0000
callback yes After all design image has been exported, the callback URL will receive a POST request containing XML result message

<?xml version="1.0" encoding="UTF-8"?>
<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>
HTTP 200

The following request will be made from our servers to the callback url, the request body will consist of XML data containing the URL to your exported project files.

POST callback
<?xml version="1.0" encoding="UTF-8"?>
<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>