Find Similar Projects

curl --request GET \
  --url https://api.n-3.co.uk/community/similar/{projectId}

const options = {method: 'GET'};

fetch('https://api.n-3.co.uk/community/similar/{projectId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.n-3.co.uk/community/similar/{projectId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.n-3.co.uk/community/similar/{projectId}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.n-3.co.uk/community/similar/{projectId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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": {}
          }
        }
      ]
    }
  ]
}

GET

community

similar

{projectId}

Find Similar Projects

curl --request GET \
  --url https://api.n-3.co.uk/community/similar/{projectId}

const options = {method: 'GET'};

fetch('https://api.n-3.co.uk/community/similar/{projectId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.n-3.co.uk/community/similar/{projectId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.n-3.co.uk/community/similar/{projectId}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.n-3.co.uk/community/similar/{projectId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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

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:

array

Array of development categories with matched projects

Show development structure

string

Name of the development category (e.g., “Primary Development”, “Secondary Development”)

object

Building profile information for the development

Show profile

string

Building function (e.g., “Educational”, “Residential”, “Commercial”)

string

Construction process (e.g., “New Build”, “Refurbishment”, “Extension”)

string

Mandatory matching criteria that all results must meet

array

Array of similar projects found in the community

Show similar project

number

Similarity score (0.0 to 1.0, where 1.0 is identical)

object

Anonymized project details

Show project details

bigint

Anonymous project identifier

number

Footprint cost of the project

number

Total project cost

number

Total Gross Internal Floor Area (GIFA) in square meters

number

Site area in square meters

number

Generalized latitude (anonymized for privacy)

number

Generalized longitude (anonymized for privacy)

string

Contract start date in ISO format

object

Location information with privacy protection

Show location

number

Location index for regional comparison

string

Generalized region (e.g., “South East”, “North West”)

object

Temporal information for market context

Show time

number

Time index for market condition comparison

array

Array of project features and characteristics

object

Detailed similarity analysis report

Show similarity report

array

Features that matched between projects

array

Features that differed between projects

object

Detailed breakdown of similarity scoring

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

error

Bad Request - Invalid project ID or malformed request

{
  "statusCode": 400,
  "message": "Invalid project ID provided.",
  "error": "Bad Request"
}

error

Forbidden - User lacks admin permissions or community access

{
  "statusCode": 403,
  "message": "User does not have permission to perform this action",
  "error": "Forbidden"
}

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

Community Sync - Trigger community data synchronisation
Benchmark Reports - Enhanced with community data
Project Data - Source project information

API Documentation

Analytics

Projects

Reports

Document Studio

Benchmarking

Community

Find Similar Projects

Path Parameters

Authentication & Authorization

Response Structure

Example Response

Similarity Scoring Algorithm

Mandatory Matching (Weight: 40%)

Feature Similarity (Weight: 30%)

Scale Similarity (Weight: 20%)

Location & Time Similarity (Weight: 10%)

Data Privacy & Anonymization

Anonymized Elements

Preserved Elements

Use Cases

Benchmarking

Risk Assessment

Market Analysis

Error Responses

Empty Results

Rate Limiting

Best Practices

Query Optimization

Data Interpretation

Community Participation

​Path Parameters

​Authentication & Authorization

​Response Structure

​Example Response

​Similarity Scoring Algorithm

​Mandatory Matching (Weight: 40%)

​Feature Similarity (Weight: 30%)

​Scale Similarity (Weight: 20%)

​Location & Time Similarity (Weight: 10%)

​Data Privacy & Anonymization

​Anonymized Elements

​Preserved Elements

​Use Cases

​Benchmarking

​Risk Assessment

​Market Analysis

​Error Responses

​Empty Results

​Rate Limiting

​Best Practices

​Query Optimization

​Data Interpretation

​Community Participation

​Related Endpoints

Path Parameters

Authentication & Authorization

Response Structure

Example Response

Similarity Scoring Algorithm

Mandatory Matching (Weight: 40%)

Feature Similarity (Weight: 30%)

Scale Similarity (Weight: 20%)

Location & Time Similarity (Weight: 10%)

Data Privacy & Anonymization

Anonymized Elements

Preserved Elements

Use Cases

Benchmarking

Risk Assessment

Market Analysis

Error Responses

Empty Results

Rate Limiting

Best Practices

Query Optimization

Data Interpretation

Community Participation

Related Endpoints