Spatial

Geospan’s Spatial APIs provide Geographic Information System (GIS) functionality that integrates with GEOSPAN services. These geospatial helper APIs are useful to assist with both gSquare and gPro applications.

The Spatial APIs allow you to retrieve spatial data, such as roof footprints, within a specified bounding box. Use these APIs, combined with data from other Geospan API, to analyze and visualize geospatial information.

Authentication

Authentication for the Spatial APIs uses the same API-Key as the gPro API. Include your API key in the Authorization header of your requests:

Authorization: Api-Key YOUR_API_KEY

Base URL

The base URL for the Spatial APIs is:

https://api.geospan.com/remote4d/v1/api/spatial/

Using the Spatial APIs with gPro Data

One way to use the Spatial APIs in conjunction with the gPro APIs is by:

  1. Retrieving GeoJSON data for a specific job from the gPro API
  2. Calculating a bounding box based on the coordinates in the GeoJSON data
  3. Using the calculated bounding box to query the Spatial API for footprints data

By following this process, you can combine the detailed structure information from the gPro APIs with the broader spatial context provided by the Spatial APIs.

Review the following Python and JavaScript examples to see gSquare in action.

Review and download example code

Note

The API keys and tokens in index.js are for demonstration only. In a real application, secure them using appropriate methods, such as environment variables, backend proxies, and IAM services with temporary credentials.

​
// Footprints API interaction script for browser environments

// Function to create and append a pre element with the given content
function appendPre(content, parent = document.getElementById('results')) {
    const pre = document.createElement('pre');
    pre.textContent = JSON.stringify(content, null, 2);
    parent.appendChild(pre);
}

// Main function to execute the API call
async function fetchFootprints(apiKey) {
    if (!apiKey) {
        console.error("API key is required");
        appendPre("Error: API key is required");
        return;
    }

    // Hardcoded bounding box coordinates
    const minLon = -93.18814705349445;
    const minLat = 44.71487409726919;
    const maxLon = -93.18663294650553;
    const maxLat = 44.715445901318304;

    const bounds = `${minLon},${minLat},${maxLon},${maxLat}`;

    // Query the Spatial API using the hardcoded bounding box
    const url = 'https://api.geospan.com/remote4d/v1/api/spatial/footprints';
    const params = new URLSearchParams({ bounds });
    const headers = {
        'Authorization': `Api-Key ${apiKey}`,
        'accept': 'application/json'
    };

    try {
        const response = await fetch(`${url}?${params}`, { headers });
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        const footprintsData = await response.json();

        console.log("Footprints data:", footprintsData);
        appendPre("Footprints data:");
        appendPre(footprintsData);

    } catch (error) {
        console.error("An error occurred:", error);
        appendPre(`An error occurred: ${error.message}`);
    }
}

// Set up event listener for form submission
document.addEventListener('DOMContentLoaded', () => {
    const form = document.getElementById('apiKeyForm');
    const resultsDiv = document.getElementById('results');

    form.addEventListener('submit', (e) => {
        e.preventDefault();
        resultsDiv.innerHTML = ''; // Clear previous results
        const apiKey = document.getElementById('apiKey').value;
        fetchFootprints(apiKey);
    });
});
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Footprints API Demo</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            line-height: 1.6;
            margin: 0;
            padding: 20px;
            max-width: 800px;
            margin: 0 auto;
        }

        h1 {
            color: #333;
        }

        form {
            margin-bottom: 20px;
        }

        input[type="text"] {
            width: 300px;
            padding: 5px;
        }

        button {
            padding: 5px 10px;
            background-color: #4CAF50;
            color: white;
            border: none;
            cursor: pointer;
        }

        button:hover {
            background-color: #45a049;
        }

        pre {
            background-color: #f4f4f4;
            border: 1px solid #ddd;
            border-radius: 4px;
            padding: 10px;
            white-space: pre-wrap;
            word-wrap: break-word;
        }
    </style>
</head>

<body>
    <h1>Footprints API Demo</h1>
    <form id="apiKeyForm">
        <label for="apiKey">Enter your API Key:</label>
        <input type="text" id="apiKey" name="apiKey" required>
        <button type="submit">Fetch Footprints</button>
    </form>
    <div id="results"></div>

    <script src="index.js"></script>
</body>

</html>
"""
Get GeoJSON from gPro API and query the Spatial API using a calculated bounding box
"""
import requests
import json
import os
import sys

GEOSPAN_API_KEY = os.getenv("GEOSPAN_API_KEY") or input("Please enter your API key: ")
API_HOME = os.getenv("GEOSPAN_API_HOME", "https://api.geospan.com/remote4d/v1/api/")

# Define the run_example function
def run_example(silent=False):
    min_lon, min_lat, max_lon, max_lat = [
        -93.18814705349445,
        44.71487409726919,
        -93.18663294650553,
        44.715445901318304,
    ]
    bounds = f"{min_lon},{min_lat},{max_lon},{max_lat}"

    # Step 3: Query the Spatial API using the calculated bounding box
    url = f"{API_HOME}/spatial/footprints"
    params = {"bounds": bounds}
    headers = {
        "Authorization": f"Api-Key {GEOSPAN_API_KEY}",
    }
    response = requests.get(url, params=params, headers=headers)
    response.raise_for_status()
    footprints_data = response.json()

    if not silent:
        # Output the footprints data
        print("Footprints data:")
        print(json.dumps(footprints_data, indent=2))

    return 0  # Return 0 to indicate success


if __name__ == "__main__":
    if not GEOSPAN_API_KEY:
        print("API key is required.")
        sys.exit(1)  # Exit with non-zero exit code for failure

    sys.exit(run_example())

Download JavaScript

Download Python