Floor Plan Detection API for Developers

Technical specifications and integration guide for building floor plan detection into your applications. REST api patterns, data formats, authentication, and implementation best practices.

This guide covers technical implementation details for integrating floor plan detection capabilities into your applications. Whether you're building a property management system, insurance platform, or space planning tool, our ai-powered API enables automated furniture and fixture detection using state-of-the-art computer vision and deep learning.

API Overview

The floor plan recognition API follows REST conventions, accepts image uploads via multipart form data, and returns json results. Built on neural network models trained with pre-trained weights, it delivers high accuracy detection. Key characteristics:

• Protocol: HTTPS (required)
• Authentication: API key via headers
• Input formats: jpg, PNG, PDF (max 10MB)
• Output format: json
• Response time: realtime for small files, async for large
• Detection: object detection with bounding boxes, segmentation

The underlying system uses cnn-based algorithms trained on a diverse dataset of real-world architectural drawings. Each prediction includes confidence scores as a metric for result quality.

Authentication

All API requests require authentication via an API key passed in the request headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

API keys can be generated through the developer dashboard. Each key can be scoped to specific operations (read-only, detection, admin).

Endpoint Reference

Submit a floor plan image for detection. Returns detection results synchronously for images under 5MB; returns a job ID for larger files requiring async processing.

Request Parameters

Parameter	Type	Required	Description
image	file	Yes	floor plan image (PNG, jpg, PDF)
documentNo	string	No	Reference identifier for the document
customer	string	No	Customer or project identifier
webhookUrl	string	No	Callback URL for async results

Example Request (cURL)

curl -X POST https://api.scanmyplan.com/v1/detect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@floorplan.jpg" \
  -F "documentNo=FP-2024-001" \
  -F "customer=acme-corp"

This curl example shows a typical bash command for uploading a jpg floor plan. The same workflow works on macos, Linux, or Windows.

Example Request (Python)

import requests

url = "https://api.scanmyplan.com/v1/detect"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
files = {"image": open("floorplan.jpg", "rb")}
data = {"documentNo": "FP-2024-001", "customer": "acme-corp"}

response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()
print(result["itemCount"], "items detected")

The python SDK handles authentication dependencies automatically. Install via pip:

pip install scanmyplan-api

Example Request (JavaScript)

const formData = new FormData();
formData.append('image', floorPlanFile);

const response = await fetch('https://api.scanmyplan.com/v1/detect', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  body: formData
});

const results = await response.json();

Our javascript SDK works in Node.js and browsers. The returned json includes detection annotations ready for your application.

Response

{
  "success": true,
  "documentNo": "FP-2024-001",
  "customer": "acme-corp",
  "itemCount": 47,
  "items": [
    {
      "ID": 1,
      "RoomNo": "101",
      "ItemName": "Styling Chair",
      "x": 245,
      "y": 180,
      "width": 45,
      "height": 38,
      "Accuracy": 0.94
    }
  ],
  "rooms": [{ "RoomNo": "101", "itemCount": 8 }],
  "resultUrl": "https://api.scanmyplan.com/results/abc123"
}

Each detection includes bounding boxes with x, y coordinates and dimensions. The Accuracy metric shows confidence (0.0-1.0) for quality filtering.

Retrieve detection results by ID. Use this endpoint to poll for results when async processing is required.

List all detection results for the authenticated account. Supports pagination and filtering by date range.

Response Format Details

Item Object

Field	Type	Description
ID	integer	Unique identifier for this detection
RoomNo	string	Room number containing this item
ItemName	string	Detected item category
x, y	integer	Top-left corner coordinates (original image scale)
width, height	integer	Dimensions of detection bounding boxes
Accuracy	float	Confidence score (0.0 - 1.0)

Webhook Integration

For production workflows, configure webhooks to receive results automatically:

{
  "event": "detection.complete",
  "timestamp": "2026-03-05T12:00:00Z",
  "data": {
    "id": "abc123",
    "documentNo": "FP-2024-001",
    "status": "completed",
    "itemCount": 47
  }
}

Configure webhooks via the dashboard or API:

curl -X POST https://api.scanmyplan.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourapp.com/webhooks/detection", "events": ["detection.complete"]}'

Docker Deployment

Run the detection service locally using docker:

docker pull scanmyplan/detection-api:latest
docker run -p 8080:8080 -e API_KEY=your_key scanmyplan/detection-api:latest

The docker image includes all dependencies and runs on macos, Linux, or Windows.

SDK Installation

Official SDKs are available for multiple languages:

# Python
pip install scanmyplan-api

# Node.js
npm install scanmyplan-sdk

# Go
go get github.com/scanmyplan/sdk-go

Each SDK handles API key encoding, request signing, and response parsing automatically.

Integration with LLMs

The API output integrates seamlessly with llms and ai assistant workflows. Send the json response to GPT, Claude, or other llms for natural language queries:

"How many styling chairs are in room 101?"
-> API returns detection results
-> LLM responds: "There are 4 styling chairs in room 101"

Advanced: Custom Model Training

For specialized floor plan analysis needs, train custom models:

# Prepare training data with annotations
python -m scanmyplan.tools.prepare_dataset \\
  --input ./floor-plans \\
  --output ./dataset.json \\
  --format coco

The training pipeline supports lidar-enhanced data fusion and custom annotation schemas. Find examples on github:

git clone https://github.com/scanmyplan/model-training.git
cd model-training
pip install -r requirements.txt

Error Handling

The API returns standard HTTP status codes:

• 200: Success
• 400: Invalid request (missing parameters, file too large)
• 401: Invalid or missing API key
• 413: File exceeds maximum size (10MB)
• 429: Rate limit exceeded
• 500: Server error

{
  "success": false,
  "error": {
    "code": "INVALID_IMAGE",
    "message": "The provided file could not be processed."
  }
}

Best Practices

Image Quality

• Use high-resolution images (minimum 1000px on longest edge)
• Ensure clear contrast between elements and background
• jpg works well for photographs, PNG for CAD exports
• Include room numbers for automatic room assignment

Error Handling

• Implement retry logic with exponential backoff
• Set appropriate timeouts (180 seconds for large files)
• Log failed requests for debugging

Security

• Never expose API keys in client-side code
• Use environment variables for key storage
• Rotate keys periodically
• Implement webhook signature verification

Getting Started

To begin integration:

1. Create an account at scanmyplan.com
2. Generate an API key from the dashboard
3. Start with the web interface to test your floor plan images
4. Integrate the api into your workflow
5. Configure webhooks for production automation