gSquare

gSquare is GEOSPAN’s “instant” roof area estimation APIs. gSquare supplies area and predominant pitch in seconds.

Use these APIs to:

• Create a new “instant” estimation task
• Monitor the progress and handle the results

Before you begin

Before starting with the gSquare APIs, take time to review the following resources:

• Get Started — set up the right account, API key, and quota
• gSquare examples — review the Python and JavaScript code examples
• Concepts — familiarize yourself with geoprocessing concepts and review the gSquare Lifecycle diagram. This asynchronous approach allows for efficient handling of potentially time-consuming estimation tasks without blocking your application:
  1. Request: You initiate the lifecycle with a request to the /estimate/ endpoint to create an estimate.
  2. Get query key: The API returns a query key immediately.
  3. Poll: You then need to poll the /query/:queryKey endpoint to monitor the status of the estimate.
  4. Monitor status: You check the response from the API, which indicates one of these statuses:
     • PENDING: The estimate is still being processed.
     • FAILURE: The estimation process encountered an error.
     • SUCCESS: The estimate is complete and results are available.
  5. Act on result:
     • If FAILURE, an error report is generated.
     • If SUCCESS, read and utilize the results.

Estimating roof areas

The following sections provide an example of the HTTP REST method for each API endpoint, along with explanations of request parameters and an example result that GEOSPAN returns.

POST /estimate

Create a new area estimation task by providing a roof footprint in Well-Known Text (WKT) format.

curl -X 'POST' \
  'https://api.geospan.com/remote4d/v1/gsquare/estimate' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key <geospanapikeystring>' \
  -H 'Content-Type: application/json' \
  -d '{
  "wkt": "POINT ( -93.18739 44.71353 )",
  "includeImagery": true,
  "includeWeather": true
}'

{
    "queryKey": "sqm-if_plI1MRIasdf1234lkjh"
}

Parameters

wkt

[required] [type: string] Well-Known Text representation of a roof footprint. Can be a POLYGON or POINT.

includeImagery

[optional] [type: boolean] Toggle whether to include oblique views. Default is false.

includeWeather

[optional] [type: boolean] Toggle whether to include weather data. Default is false.

model

[optional] [type: string] Specify the model to use for estimation. Default is “default”.

GET /query/{query_key}

Retrieve the status and results of a specific estimation task using the query key returned by the POST /estimate endpoint.

curl -X 'GET' \
  'https://api.geospan.com/remote4d/v1/gsquare/query/abcd1234-5678-90ef-ghij-klmnopqrstuv' \
  -H 'accept: application/json' \
  -H 'Authorization: Api-Key <geospanapikeystring>'

{
    "computedFootprint": "POLYGON ((-93.187349 44.713629, -93.187347 44.713569, -93.187328 44.713569, -93.187322 44.71344, -93.187381 44.713439, -93.187381 44.713425, -93.187413 44.713425, -93.187414 44.713441, -93.187441 44.713441, -93.18745 44.713627, -93.187349 44.713629))",
    "totalArea": {
        "area": 197.8059923890073,
        "units": "sqm"
    },
    "pitchResult": {
        "primaryPitch": 3,
        "deviation": 1
    },
    "confidence": 6,
    "imagery": [
        {
            "orientation": "nadir",
            "image": "/9j/4AAQSkZJRgABAgAAAQABAAD/4QjKaHR0cDov
            .
            .
            .
            61TvbxGcBRkY5OakkJkyJGI+lVZoUGQG604os//2Q=="
        },
        {
            "orientation": "north",
            "image": "/9j/4AAQSkZJRgABAgAAAQABAAD/4QiwaHR0cDov
            .
            .
            .
            WzZUQnbvPeolBsGrn/2Q=="
        },
        {
            "orientation": "east",
            "image": "/9j/4AAQSkZJRgABAgAAAQABAAD/4Qi9aHR0cDov
            .
            .
            .
            ZP/AIql9al0gwVFPqf/2Q=="
        },
        {
            "orientation": "south",
            "image": "/9j/4AAQSkZJRgABAgAAAQABAAD/4QiuaHR0cDov
            .
            .
            .
            /+tWcqji9hXR//9k="
        },
        {
            "orientation": "west",
            "image": "/9j/4AAQSkZJRgABAgAAAQABAAD/4Qi+aHR0cDov
            .
            .
            .
            pnMBiIeNTuZcEdQf5UquF5WjOULM//2Q=="
        }
    ],
    "weather": [
        {
            "datecode": "231024",
            "hailSize": 1,
            "distance": 9.760984757545051
        },
        {
            "datecode": "240803",
            "hailSize": 1,
            "distance": 7.845437799202324
        }
    ]
}

Parameters

query_key

[required] [type: string] The unique identifier for the gSquare query.