REST API v0.2

API Documentation

Convert IFC and BIM files to geospatial formats programmatically. Full property preservation, automatic CRS detection, 3D geometry, and pipe generation via a simple REST API.

GeoJSONGeoPackageShapefileFile GDB

Quick Start

The fastest way to convert an IFC file is a single curl command. No API key is required for the free tier.

Upload and convert (one-step)

curl -X POST https://api.mightyspatial.com/api/convert \
  -F "file=@model.ifc" \
  -F "output_format=geojson" \
  -o output.geojson

Two-step: Preview then download

# Step 1 — Upload and preview
curl -X POST https://api.mightyspatial.com/api/convert/preview \
  -F "file=@model.ifc" \
  -F "source_crs=EPSG:7856"

# Step 2 — Download using the job_id from Step 1
curl "https://api.mightyspatial.com/api/convert/download/{job_id}?output_format=geopackage" \
  -o output.gpkg

With API key (Pro/Enterprise)

curl -X POST https://api.mightyspatial.com/api/convert/preview \
  -H "X-API-Key: msp_live_your_key_here" \
  -F "file=@model.ifc"

Python SDK

Install the Python SDK for scripting and notebook workflows. Supports direct output to pandas and geopandas DataFrames.

Install

pip install mightyspatial          # core
pip install mightyspatial[geo]     # + geopandas support
pip install mightyspatial[pandas]  # + pandas only

Convert to file

from mightyspatial import convert

# Returns the path to the saved output file
path = convert("building.ifc", output_format="geojson")
path = convert("building.ifc", output_format="geopackage", api_key="ms_...")

Convert to GeoDataFrame

from mightyspatial import to_geodataframe

# Returns a geopandas GeoDataFrame (geometry + attributes)
gdf = to_geodataframe("building.ifc")
gdf = to_geodataframe("building.ifc", api_key="ms_...", source_crs="EPSG:28356")
gdf.plot()
gdf.to_file("output.gpkg", driver="GPKG")

Convert to DataFrame

from mightyspatial import to_dataframe

# Returns a pandas DataFrame (attributes only, no geometry)
df = to_dataframe("building.ifc")
df.head()
df.to_csv("attributes.csv")

Using the client class

from mightyspatial import MightySpatial

ms = MightySpatial(api_key="ms_...")
gdf = ms.to_geodataframe("building.ifc")      # GeoDataFrame
df  = ms.to_dataframe("building.ifc")          # DataFrame
path = ms.convert("building.ifc")              # file path

Authentication

The API uses key-based authentication via the X-API-Key header. Free-tier requests do not require a key.

Tier	API Key	Formats
Free	Not required	GeoJSON
Pro	Required	GeoJSON, GeoPackage, Shapefile
Enterprise	Required	All formats (incl. File GDB)

API keys follow the format msp_live_xxxxxxxxxxxx (production) or msp_test_xxxxxxxxxxxx (sandbox).

GET

/api/health

Returns service status and version. Use this to verify the API is reachable.

Response

{
  "status": "ok",
  "version": "0.2.0"
}

curl

curl https://api.mightyspatial.com/api/health

GET

/api/formats

Lists supported output formats and their minimum tier requirements.

Response

{
  "formats": [
    {
      "format": "geojson",
      "extension": ".geojson",
      "mime_type": "application/geo+json",
      "min_tier": "free",
      "description": "GeoJSON (RFC 7946)"
    },
    {
      "format": "geopackage",
      "extension": ".gpkg",
      "mime_type": "application/geopackage+sqlite3",
      "min_tier": "pro",
      "description": "OGC GeoPackage"
    },
    {
      "format": "shapefile",
      "extension": ".shp",
      "mime_type": "application/x-shapefile",
      "min_tier": "pro",
      "description": "Esri Shapefile"
    },
    {
      "format": "filegdb",
      "extension": ".gdb",
      "mime_type": "application/x-filegdb",
      "min_tier": "enterprise",
      "description": "Esri File Geodatabase"
    }
  ]
}

curl

curl https://api.mightyspatial.com/api/formats

POST

/api/convert/preview

Upload an IFC file and receive GeoJSON layers for in-browser preview. Returns a job_id used for subsequent download requests. Layers are cached server-side for 10 minutes.

Parameters

Parameter	In	Type	Required	Notes
file	form	file	Yes	.ifc file
source_crs	form	string	No	EPSG code (e.g. EPSG:7856). Auto-detected if omitted.
split_attributes	form	string	No	Comma-separated attribute names for layer sub-grouping
split_groups	form	string	No	JSON object mapping group names to attribute value lists
X-API-Key	header	string	No	API key for Pro/Enterprise tiers

Response

{
  "job_id": "a1b2c3d4e5f6",
  "layers": [
    {
      "name": "LineString",
      "feature_count": 338,
      "geometry_type": "LineString",
      "geojson": {
        "type": "FeatureCollection",
        "features": [...]
      }
    }
  ],
  "available_attributes": ["AssetType", "className", "name"],
  "detected_crs": "EPSG:7856"
}

curl

curl -X POST https://api.mightyspatial.com/api/convert/preview \
  -F "file=@model.ifc" \
  -F "source_crs=EPSG:7856" \
  -F "split_attributes=AssetType,className"

Coordinate system note

All GeoJSON coordinates in the preview response are reprojected to WGS 84 (EPSG:4326) for display. Downloads use the original source CRS.

GET

/api/convert/download/{job_id}

Download the cached conversion result in the requested format.

Parameters

Parameter	In	Type	Required	Notes
job_id	path	string	Yes	From the preview response
output_format	query	string	No	geojson (default), geopackage, shapefile, filegdb

Response: Binary file download with Content-Disposition header.

curl

curl "https://api.mightyspatial.com/api/convert/download/a1b2c3d4e5f6?output_format=geopackage" \
  -o output.gpkg

POST

/api/convert/download/{job_id}

Download with the current layer structure. The client POSTs its layers array so the download respects any client-side splits, merges, or pipe layers.

Parameters

Parameter	In	Type	Required	Notes
job_id	path	string	Yes	From the preview response

Request Body (JSON)

Field	Type	Default	Notes
output_format	string	geojson	geojson, geopackage, shapefile, filegdb
base_filename	string	output	Base name for the output file(s)
include_csv	boolean	false	When true, bundles CSV exports per layer in a zip archive
layers	array	(required)	Array of layer objects with name, geometry_type, and features

Request body example

{
  "output_format": "geopackage",
  "base_filename": "my_project",
  "include_csv": false,
  "layers": [
    {
      "name": "LineString",
      "geometry_type": "LineString",
      "features": [...]
    }
  ]
}

POST

/api/convert/pipes/{job_id}

Generate real 3D pipe geometry (MultiPolygon tube surfaces) from polyline features. The tube surface is swept along the 3D centreline with circular cross-sections.

Path Parameters

Parameter	In	Type	Required	Notes
job_id	path	string	Yes	From the preview response

Request Body (JSON)

Field	Type	Default	Notes
source_layer	string	(required)	Name of the source polyline layer
features	array	(required)	GeoJSON Feature dicts from the source layer
diameter_field	string\|null	null	Attribute name containing pipe diameter values
config_field	string\|null	null	Attribute for bank/array config (e.g. "2x100;3x150")
uom	string	mm	Unit of measurement: mm, cm, in, ft, m, km
default_diameter	number	300	Default diameter when no field is specified
centerline_mode	string	centerline	centerline, topSeam, or bottomSeam
bank_centerline_mode	string	centerline	Array/bank reference: centerline, topSeam, bottomSeam
bank_stack_direction	string	bottomUp	Stack direction: bottomUp or topDown
bank_gap	number	50	Gap between pipes in the array (in uom units)
bank_expression_schema	object\|null	null	Custom expression template for parsing bank config strings
segments	integer	8	Facets around the tube cross-section (higher = smoother)

Request body example

{
  "source_layer": "LineString",
  "features": [...],
  "diameter_field": "Diameter",
  "config_field": "PipeConfig",
  "uom": "mm",
  "default_diameter": 300,
  "centerline_mode": "centerline",
  "segments": 8
}

Response

{
  "layer": {
    "name": "Pipe3D: LineString",
    "feature_count": 42,
    "geometry_type": "MultiPolygon",
    "geojson": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "MultiPolygon",
            "coordinates": [...]
          },
          "properties": {
            "AssetType": "SEWER",
            "_pipeDiameter": 0.3,
            "_pipeOffsetRight": 0.0,
            "_pipeOffsetUp": 0.0,
            "_is3DPipe": true
          }
        }
      ]
    }
  }
}

curl

curl -X POST https://api.mightyspatial.com/api/convert/pipes/a1b2c3d4e5f6 \
  -H "Content-Type: application/json" \
  -d '{
    "source_layer": "LineString",
    "features": [...],
    "diameter_field": "Diameter",
    "uom": "mm",
    "default_diameter": 300,
    "segments": 12
  }'

Bank expression schema (Pro feature)

When bank_expression_schema is null, the default fixed format 2x100;3x150 is used (row count x diameter, semicolon-separated). Provide a custom template to parse any format.

Custom bank expression example

{
  "expression": "{diameter}{diameter_uom}{multiplier}{row_width}{new_row}",
  "literals": {
    "multiplier": "*",
    "diameter_uom": "mm",
    "new_row": "|"
  }
}
// Parses: "100mm*2|150mm*3"

POST

/api/convert

Legacy

Upload an IFC file and receive the converted output as a streaming download in a single request. Does not cache layers. For new integrations, prefer the two-step preview/download workflow.

Parameters

Parameter	In	Type	Required	Notes
file	form	file	Yes	.ifc file
output_format	form	string	No	geojson (default), geopackage, shapefile, filegdb
source_crs	form	string	No	EPSG code. Auto-detected if omitted.
split_attributes	form	string	No	Comma-separated attribute names for layer sub-grouping
split_groups	form	string	No	JSON group mapping (same format as preview endpoint)
strip_prefix	form	string	No	Prefix to strip from property names (e.g. _12dModel)
strip_suffix	form	string	No	Suffix to strip from property names
X-API-Key	header	string	No	API key for Pro/Enterprise tiers

curl

curl -X POST https://api.mightyspatial.com/api/convert \
  -F "file=@model.ifc" \
  -F "output_format=geojson" \
  -F "strip_prefix=_12dModel" \
  -o output.geojson

Properties Reference

Standard IFC Properties

Every converted feature includes these base properties:

Property	Type	Description
expressId	number	IFC entity numeric ID
globalId	string	IFC GlobalId (UUID)
className	string	IFC class name (e.g. IfcPipe, IfcWall)
name	string	Entity Name attribute
description	string	Entity Description
objectType	string	Entity ObjectType

12d Model Properties

Properties from 12d Model property sets are preserved with their raw names (e.g. _12dModelAssetType). The _12dModel prefix is no longer auto-stripped during upload. To strip prefixes or suffixes on demand, use the strip_prefix and strip_suffix form parameters on the /api/convert endpoint. The frontend also provides a client-side strip tool in the attribute table.

Property	Description
_12dModelAssetType	Asset classification (e.g. TELECOMMUNICATIONS, SEWER)
_12dModelSurveyDatum	Survey datum reference

Pipe Geometry Properties

Properties added to features generated by the pipe geometry endpoint:

Property	Type	Description
_pipeDiameter	number	Pipe diameter in metres
_pipeOffsetRight	number	Lateral offset from centreline in metres (bank mode)
_pipeOffsetUp	number	Vertical offset from centreline in metres (bank mode)
_is3DPipe	boolean	Always true; marks features as generated pipe geometry

Polyline Segment Properties

Features extracted from polyline-based IFC elements include:

Property	Type	Description
_parentId	number	Parent entity expressId
_parentType	string	Parent entity class name
_segmentId	number	Segment index within the polyline
_vertexIndex	number	Vertex index for point features
_isPolyline	boolean	Always true for polyline-derived features
_segmentCount	number	Total segments in the parent polyline

Error Codes

All error responses follow a consistent JSON format:

{
  "detail": "Human-readable error message"
}

Status	Meaning
400	Bad request (invalid file, no geometry, missing features)
401	Missing or invalid API key (for tier-restricted features)
403	Tier too low for requested format
404	Job not found or expired
413	File too large for tier
429	Rate limit exceeded
500	Internal server error
501	Feature not yet implemented

Rate Limits & File Size

Rate limits are applied per IP address (free tier) or per API key (Pro/Enterprise).

Tier	Rate Limit	Max File Size	Price	Output Formats
Free	5 requests / month	25 MB	Free	GeoJSON, GeoPackage, Shapefile
Pro	100 credits / month	500 MB	$100 / month	All (incl. File GDB)
Enterprise	Unlimited	2 GB	Custom	All (incl. File GDB)

Enterprise plans also include a desktop application and Python library for on-premise deployment, offline conversion, and integration into existing data pipelines.

Subscription pricing: Pro tier is $100/month with 100 credits included (1 credit = 100 MB). Files up to 500 MB are supported — a 500 MB file uses 5 credits. Unused credits roll over for 3 months. Overage is billed at $0.50 per credit. Free tier includes 5 conversions per month (up to 25 MB) — no signup required.

Cache expiry

Preview results are cached server-side for 10 minutes. After expiry, the job_id becomes invalid and you will need to re-upload the file.

Ready to integrate?

Start converting IFC files to GIS formats with a single API call. No signup required for the free tier.

Try the Converter Contact Sales