Instant Design Components

Authentication ​

All API requests require authentication using your API key. Set the X-Api-Key header:

javascript
const apiHeaders = new Headers();
apiHeaders.set('X-Api-Key', 'your-api-key-here');
apiHeaders.set('Content-Type', 'application/json');

WARNING

Do not expose your API key to the client. All API requests must be proxied through your backend.

Find your API key at: mapdwell.com/account/api

Full API documentation is available at: mapdwell.com/account/api/documentation

Endpoints ​

POST /api/v2/papi/rooftop_geometries ​

  • Request body
    • lat: number
    • lon: number
    • Optionally include survey_types: string[] with one or more of: ["google_dsm","lidar"]
  • 422 response if no rooftop geometry can be created for the given lat/lon
  • Pass this response into the PVSystemDesigner as rooftopGeometryResponse

GET /api/v2/papi/rooftop_geometries/:id ​

  • Retrieves an existing rooftop geometry by ID
  • Use this for subsequent requests after initial geometry creation
  • 404 response if rooftop geometry not found

POST /api/v2/papi/rooftop_geometries/:rooftop_geometry_id/pv_system ​

  • Body: see docs for full list of parameters
  • Make your initial request to this endpoint with your preferred panel_length, panel_width, setback_distance, and target_num_panels
  • If you want to enable the component's full design capabilities, the PVSystemDesigner's onPVSystemRequestParamsChange callback will be called with the new request params
  • Pass this response into the PVSystemDesigner as pvSystemResponse

Response time expectations ​

  • Rooftop geometry (POST): residential roofs typically take 5-20 seconds
  • Rooftop geometry (GET by id): under a second
  • PV system (POST): about 1 second for the first request, 100ms for subsequent requests We recommend designing your application to make the rooftop geometry call early in your user flow.

Rooftop geometries are stored for 30 days. GETing a previously created rooftop geometry has no cost associated with it, and is much faster than creating a new one.

PV system POSTs are idempotent with the same inputs; you can cache outputs for up to 30 days for display/estimation UX.

UX tips ​

  • Debounce/tail-cancel PV system requests; only render the latest response