Skip to main content
GET
/
community
/
similar
/
{projectId}
Find Similar Projects
curl --request GET \
  --url https://api.n-3.co.uk/community/similar/{projectId}
{
  "400": {},
  "403": {},
  "404": {},
  "developments": [
    {
      "name": "<string>",
      "profile": {
        "function": "<string>",
        "process": "<string>"
      },
      "mandatory": "<string>",
      "results": [
        {
          "similarity": 123,
          "details": {
            "id": {},
            "footprint_cost": 123,
            "total_cost": 123,
            "total_gifa": 123,
            "site_area": 123,
            "latitude": 123,
            "longitude": 123,
            "contract_start_date": "<string>"
          },
          "location": {
            "index": 123,
            "region": "<string>"
          },
          "time": {
            "index": 123
          },
          "features": [
            {}
          ],
          "report": {
            "matches": [
              {}
            ],
            "differences": [
              {}
            ],
            "score_breakdown": {}
          }
        }
      ]
    }
  ]
}
Discover similar projects from the platform community based on sophisticated matching algorithms that consider building function, construction process, project scale, and other characteristics. This endpoint provides access to anonymized project data for benchmarking and comparative analysis.
This endpoint requires admin permissions and that your organization participates in community data sharing.

​
Path Parameters

​
projectId
bigint
required
The unique identifier of the project for which you want to find similar community projects

​
Authentication & Authorization

  • Required: Valid JWT token or API key
  • Permissions: User must have admin authority within their organization
  • Community Access: Organization must be a member of at least one active community

​
Response Structure

The response is organized by development type, with each development containing matched projects:
​
developments
array
Array of development categories with matched projects

​
Example Response

{
  "developments": [
    {
      "name": "Primary Development",
      "profile": {
        "function": "Educational",
        "process": "New Build"
      },
      "mandatory": "New Build Education",
      "results": [
        {
          "similarity": 0.85,
          "details": {
            "id": "community_project_12345",
            "footprint_cost": 1250000,
            "total_cost": 2100000,
            "total_gifa": 3500,
            "site_area": 8000,
            "latitude": 51.5,
            "longitude": -0.1,
            "contract_start_date": "2023-03-15T00:00:00.000Z"
          },
          "location": {
            "index": 88.5,
            "region": "South East"
          },
          "time": {
            "index": 95.2
          },
          "features": [
            "Sustainable Design",
            "Modern Construction Methods",
            "Urban Location",
            "Multi-Storey",
            "Steel Frame Construction"
          ],
          "report": {
            "matches": [
              "Building Function: Educational",
              "Construction Process: New Build",
              "Sustainable Design Features",
              "Steel Frame Construction",
              "Urban Site Location"
            ],
            "differences": [
              "Site Area: 20% larger",
              "GIFA: 15% smaller",
              "Contract Start: 6 months earlier"
            ],
            "score_breakdown": {
              "mandatory_match": 1.0,
              "feature_similarity": 0.82,
              "scale_similarity": 0.78,
              "location_similarity": 0.91,
              "overall_score": 0.85
            }
          }
        },
        {
          "similarity": 0.78,
          "details": {
            "id": "community_project_67890",
            "footprint_cost": 980000,
            "total_cost": 1850000,
            "total_gifa": 3200,
            "site_area": 7200,
            "latitude": 51.4,
            "longitude": -0.3,
            "contract_start_date": "2023-09-01T00:00:00.000Z"
          },
          "location": {
            "index": 87.2,
            "region": "South East"
          },
          "time": {
            "index": 92.8
          },
          "features": [
            "Traditional Construction",
            "Suburban Location",
            "Two Storey",
            "Brick Construction",
            "Standard Specifications"
          ],
          "report": {
            "matches": [
              "Building Function: Educational",
              "Construction Process: New Build",
              "Two Storey Design",
              "Regional Location"
            ],
            "differences": [
              "Construction Method: Traditional vs Modern",
              "Location: Suburban vs Urban",
              "Materials: Brick vs Steel Frame",
              "Total Cost: 12% lower"
            ],
            "score_breakdown": {
              "mandatory_match": 1.0,
              "feature_similarity": 0.65,
              "scale_similarity": 0.85,
              "location_similarity": 0.76,
              "overall_score": 0.78
            }
          }
        }
      ]
    }
  ]
}

​
Similarity Scoring Algorithm

The similarity scoring considers multiple factors:

​
Mandatory Matching (Weight: 40%)

  • Building Function: Must match exactly (e.g., Educational, Residential)
  • Construction Process: Must match exactly (e.g., New Build, Refurbishment)
  • Projects without mandatory matches are excluded from results

​
Feature Similarity (Weight: 30%)

  • Building Characteristics: Sustainable design, construction methods, specifications
  • Site Characteristics: Urban/suburban location, access, constraints
  • Design Features: Multi-storey, accessibility features, special requirements

​
Scale Similarity (Weight: 20%)

  • Cost Comparison: Footprint cost and total cost relative to project scale
  • Size Metrics: GIFA, site area, and other dimensional comparisons
  • Proportional Analysis: Ratios and per-unit metrics

​
Location & Time Similarity (Weight: 10%)

  • Regional Factors: Economic conditions, labor costs, material availability
  • Market Timing: Construction market conditions at time of contract
  • Geographic Proximity: Generalized location similarity

​
Data Privacy & Anonymization

All community data is fully anonymized:

​
Anonymized Elements

  • Organization Identity: Source organization never revealed
  • Project Names: All identifying project information removed
  • Client Information: No client or stakeholder data included
  • Precise Location: Coordinates generalized to protect specific sites

​
Preserved Elements

  • Building Characteristics: Function, process, features maintained
  • Scale Information: Costs, areas, and dimensions preserved
  • Regional Context: Generalized location for market comparison
  • Timeline Data: Contract dates for market timing analysis

​
Use Cases

​
Benchmarking

  • Compare project costs against similar community projects
  • Validate budget estimates using real project data
  • Understand cost variations across regions and time periods

​
Risk Assessment

  • Identify potential risks based on similar project experiences
  • Understand success factors from comparable developments
  • Assess project feasibility against similar developments

​
Market Analysis

  • Understand current market rates for similar projects
  • Analyze trends in construction costs and methods
  • Compare regional variations in project delivery

​
Error Responses

​
400
error
Bad Request - Invalid project ID or malformed request
{
  "statusCode": 400,
  "message": "Invalid project ID provided.",
  "error": "Bad Request"
}
​
403
error
Forbidden - User lacks admin permissions or community access
{
  "statusCode": 403,
  "message": "User does not have permission to perform this action",
  "error": "Forbidden"
}
​
404
error
Not Found - Project not found or user lacks access
{
  "statusCode": 404,
  "message": "Project not found or you do not have access to this project.",
  "error": "Not Found"
}

​
Empty Results

If no similar projects are found, the endpoint returns an empty array: 
{
  "developments": []
}
This can occur when:
  • Project characteristics are highly unique
  • Community data is limited for the project type
  • Organization is not connected to relevant communities

​
Rate Limiting

This endpoint may be subject to rate limiting due to its computational intensity:
  • Rate Limit: 10 requests per minute per user
  • Headers: Rate limit information included in response headers
  • Retry: Use exponential backoff for rate-limited requests

​
Best Practices

​
Query Optimization

  • Ensure project has complete characteristic data for better matching
  • Regular project data updates improve matching accuracy
  • Consider regional and temporal factors in analysis

​
Data Interpretation

  • Use similarity scores as guidance, not absolute measures
  • Consider the similarity report for context on matches and differences
  • Factor in market conditions and regional variations

​
Community Participation

  • Contributing data improves results for all community members
  • Regular data synchronisation ensures current community database
  • Quality project data leads to better similarity matching