Planning a Site Analysis API Integration: Contract and Evidence Checks
A technical checklist for an agreed site-analysis integration, covering credentials, job completion, safe retries and partial results without assuming a public REST API.
Quick answer
Before planning a site-analysis API integration, confirm that a supported public contract exists for the operations you need. The reviewed backend code does not by itself establish a public REST service, and the current OpenAPI reference publishes no callable operations. Use verified connected-tool discovery for supported workflows, or obtain an agreed integration contract before building a batch service.
A batch workflow should make evidence easier to compare and missing data easier to spot. The steps below are a design checklist for an agreed integration, not instructions for a currently verified public REST API. Connected-tool availability and REST availability are separate questions; check the current developer documentation and actual tool discovery.
Define the decision and input contract
Begin with the question the batch must support: selecting sites for further investigation, identifying missing evidence or comparing a small set of options. Preserve a stable internal site identifier, submitted boundary, coordinate reference and request date. Validate geometries and required fields against the current developer documentation. Test representative small, complex and invalid inputs before expanding the workload.
Keep authentication and limits explicit
The backend code reviewed includes API-key authentication and rate-limit handling. Those internal controls are not proof of a supported public endpoint or customer entitlement. For any agreed integration, keep credentials server-side and confirm how access is issued, scoped and revoked. Do not infer quotas, prices or access rights from historical articles or internal function names.
Handle asynchronous work and retries deliberately
Where an endpoint returns a job identifier or an accepted response, persist that identifier and use its documented completion mechanism. Do not assume webhooks exist. Bound concurrency and back off on rate limits. Before retrying a job-creation request after a timeout, check whether the contract provides idempotency or a way to recover the original job; avoid accidental duplicate billable work.
Validate results before comparison
Check status, requested versus returned fields, source metadata and warnings. Distinguish a failed or absent result from a negative finding. Preserve raw responses according to your data policy and build a separate reviewed summary. Test error and partial-result handling using fixtures, including missing geometry, unavailable evidence and interrupted jobs.
Create a review queue and handover
Show reviewers the same fields for each site, together with gaps and the assumptions behind any comparison. A high score must not hide an unresolved mandatory condition. Export only the files actually returned and test their units and placement separately. Record who reviewed each finding and which further source check or specialist investigation is required.
Measure the whole workflow
Evaluate preparation, processing, review, correction and downstream handover time on representative sites. Also track evidence coverage and the decisions changed by review. A quick response is not proof of accurate or complete analysis, and a locally successful integration is not evidence of production reliability under every service condition.
Illustrative example
Illustrative scenario: A team tests a small batch against a confirmed integration contract, records failed and incomplete requests separately and reviews material findings before comparing sites. A completed request does not establish complete site coverage.
Frequently asked
Does the API expose every feature in the web application?
No public REST feature parity is established. The current OpenAPI reference publishes no callable operations; verify connected-tool discovery separately and agree a supported contract for any REST integration.
Can this article establish my quota or per-site completion time?
No. Confirm account limits and measure representative requests under actual conditions.
Should an empty result be treated as no constraint?
No. Determine whether it means no feature found, unavailable data, an omitted topic or a failed request.
Can we test error handling without calling live services?
Yes. Use fixtures for validation, authentication failures, rate limits, partial responses and job lifecycle transitions.
Conclusion
Confirm the supported integration route before implementing a batch service. Once a contract is agreed, validate inputs, partial results and review responsibilities on a small batch, then connect the evidence to the site-feasibility decision.
About the author
Shatakshi Patil
Architect writing about pre-construction due diligence, planning context, and site intelligence workflows for design teams using Atlasly.
Related articles
Auto-suggested
pre-construction site analysis
Pre-Construction Site Analysis: The Complete Guide for Architects and Engineers
A comprehensive guide to zoning, flood risk, solar, topography, transport, demographics, reports, and CAD-ready outputs in pre-construction workflows.
Read
AI-powered site analysis vs manual research
AI-Powered Site Analysis vs Manual Research: A Comparison for Architecture Firms
A practical comparison of AI-assisted site analysis and traditional manual desk research for architecture and planning teams.
Read
site intelligence report
Shareable Site Intelligence Reports: Evidence, Gaps and Handover
How to prepare a traceable site report with source dates, coverage limits, unresolved issues, access checks and reviewed outputs for the next project decision.
Read
flood risk assessment site analysis
Flood Risk Assessment in Site Analysis: What Architects and Engineers Need to Know
How to interpret flood zones, water-related constraints, and design implications during early-stage site analysis for architecture and engineering teams.
Read