> ## Documentation Index
> Fetch the complete documentation index at: https://docs.n-3.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Find Similar Projects

> Discover similar projects from the community based on building characteristics, scale, and other project attributes

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.

<Note>
  This endpoint requires admin permissions and that your organization
  participates in community data sharing.
</Note>

## Path Parameters

<ParamField path="projectId" type="bigint" required>
  The unique identifier of the project for which you want to find similar
  community projects
</ParamField>

## 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:

<ResponseField name="developments" type="array">
  Array of development categories with matched projects

  <Expandable title="development structure">
    <ResponseField name="name" type="string">
      Name of the development category (e.g., "Primary Development", "Secondary
      Development")
    </ResponseField>

    <ResponseField name="profile" type="object">
      Building profile information for the development

      <Expandable title="profile">
        <ResponseField name="function" type="string">
          Building function (e.g., "Educational", "Residential", "Commercial")
        </ResponseField>

        <ResponseField name="process" type="string">
          Construction process (e.g., "New Build", "Refurbishment", "Extension")
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="mandatory" type="string">
      Mandatory matching criteria that all results must meet
    </ResponseField>

    <ResponseField name="results" type="array">
      Array of similar projects found in the community

      <Expandable title="similar project">
        <ResponseField name="similarity" type="number">
          Similarity score (0.0 to 1.0, where 1.0 is identical)
        </ResponseField>

        <ResponseField name="details" type="object">
          Anonymized project details

          <Expandable title="project details">
            <ResponseField name="id" type="bigint">
              Anonymous project identifier
            </ResponseField>

            <ResponseField name="footprint_cost" type="number">
              Footprint cost of the project
            </ResponseField>

            <ResponseField name="total_cost" type="number">
              Total project cost
            </ResponseField>

            <ResponseField name="total_gifa" type="number">
              Total Gross Internal Floor Area (GIFA) in square meters
            </ResponseField>

            <ResponseField name="site_area" type="number">
              Site area in square meters
            </ResponseField>

            <ResponseField name="latitude" type="number">
              Generalized latitude (anonymized for privacy)
            </ResponseField>

            <ResponseField name="longitude" type="number">
              Generalized longitude (anonymized for privacy)
            </ResponseField>

            <ResponseField name="contract_start_date" type="string">
              Contract start date in ISO format
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="location" type="object">
          Location information with privacy protection

          <Expandable title="location">
            <ResponseField name="index" type="number">
              Location index for regional comparison
            </ResponseField>

            <ResponseField name="region" type="string">
              Generalized region (e.g., "South East", "North West")
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="time" type="object">
          Temporal information for market context

          <Expandable title="time">
            <ResponseField name="index" type="number">
              Time index for market condition comparison
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="features" type="array">
          Array of project features and characteristics
        </ResponseField>

        <ResponseField name="report" type="object">
          Detailed similarity analysis report

          <Expandable title="similarity report">
            <ResponseField name="matches" type="array">
              Features that matched between projects
            </ResponseField>

            <ResponseField name="differences" type="array">
              Features that differed between projects
            </ResponseField>

            <ResponseField name="score_breakdown" type="object">
              Detailed breakdown of similarity scoring
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Response

```json theme={null}
{
  "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

<ResponseField name="400" type="error">
  **Bad Request** - Invalid project ID or malformed request

  ```json theme={null}
  {
    "statusCode": 400,
    "message": "Invalid project ID provided.",
    "error": "Bad Request"
  }
  ```
</ResponseField>

<ResponseField name="403" type="error">
  **Forbidden** - User lacks admin permissions or community access

  ```json theme={null}
  {
    "statusCode": 403,
    "message": "User does not have permission to perform this action",
    "error": "Forbidden"
  }
  ```
</ResponseField>

<ResponseField name="404" type="error">
  **Not Found** - Project not found or user lacks access

  ```json theme={null}
  {
    "statusCode": 404,
    "message": "Project not found or you do not have access to this project.",
    "error": "Not Found"
  }
  ```
</ResponseField>

## Empty Results

If no similar projects are found, the endpoint returns an empty array:

```json theme={null}
{
  "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

## Related Endpoints

* [Community Sync](/api-reference/community/sync-data) - Trigger community data synchronisation
* [Benchmark Reports](/api-reference/benchmark/create-benchmark-report) - Enhanced with community data
* [Project Data](/api-reference/projects/find-project-by-id) - Source project information