Atlasomi

Atlasomi Developer API

RESTful API for automated geospatial data extraction with comprehensive examples and documentation

v2 Latest API Version
REST Architecture
JSON Response Format

Base URL

https://your-atlasomi-instance.com/api/v2

All API endpoints are relative to this base URL. Replace your-atlasomi-instance.com with your actual Atlasomi deployment URL.

Authentication

Currently, the Atlasomi API operates without authentication for development and testing purposes. In production deployments, API keys or OAuth2 authentication may be required.

Note: Authentication requirements may vary based on your deployment configuration.

Extract Geospatial Data (v2)

POST /api/v2/extract

Extract raw geospatial data from multiple sources for a specified area of interest.

Request Body

{
  "aoi_boundary": {
    "type": "Polygon",
    "coordinates": [
      [
        [36.8219, -1.2921],
        [36.8250, -1.2921],
        [36.8250, -1.2950],
        [36.8219, -1.2950],
        [36.8219, -1.2921]
      ]
    ]
  },
  "sources": {
    "microsoft_buildings": {
      "enabled": true,
      "timeout": 30
    },
    "google_buildings": {
      "enabled": true,
      "timeout": 30
    },
    "osm_roads": {
      "enabled": true,
      "timeout": 25
    }
  },
  "export_format": "kmz"
}

Parameters

Parameter Type Required Description
aoi_boundary GeoJSON Polygon Yes Area of interest boundary in GeoJSON format
sources Object Yes Data source configuration with enable/disable flags
export_format String No Immediate export format: "geojson", "kml", "kmz", or "csv"

cURL Example

curl -X POST "https://your-atlasomi-instance.com/api/v2/extract" \
  -H "Content-Type: application/json" \
  -d '{
    "aoi_boundary": {
      "type": "Polygon",
      "coordinates": [[[36.8219, -1.2921], [36.8250, -1.2921], [36.8250, -1.2950], [36.8219, -1.2950], [36.8219, -1.2921]]]
    },
    "sources": {
      "microsoft_buildings": {"enabled": true},
      "osm_roads": {"enabled": true}
    }
  }'

Validate Area of Interest

POST /api/v2/validate

Validate AOI geometry and get processing estimates before extraction.

cURL Example

curl -X POST "https://your-atlasomi-instance.com/api/v2/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "aoi_boundary": {
      "type": "Polygon", 
      "coordinates": [[[36.8219, -1.2921], [36.8250, -1.2921], [36.8250, -1.2950], [36.8219, -1.2950], [36.8219, -1.2921]]]
    }
  }'

List Available Data Sources

GET /api/v2/sources

Get information about available data sources and their capabilities.

cURL Example

curl -X GET "https://your-atlasomi-instance.com/api/v2/sources"

Download Results

GET /api/v2/download/{job_id}/{format}

Download processed results in the specified format.

cURL Example

# Download as KMZ file
curl -X GET "https://your-atlasomi-instance.com/api/v2/download/550e8400-e29b-41d4-a716-446655440000/kmz" \
  -o "extracted_data.kmz"

# Download as GeoJSON
curl -X GET "https://your-atlasomi-instance.com/api/v2/download/550e8400-e29b-41d4-a716-446655440000/geojson" \
  -o "extracted_data.geojson"

Upload Design File

POST /api/v2/designs/upload

Upload design files (GeoJSON, KML, KMZ) for map visualization and reference.

cURL Example

curl -X POST "https://your-atlasomi-instance.com/api/v2/designs/upload" \
  -F "file=@network_design.kml"

Render Design on Map

POST /api/v2/designs/render

Render uploaded design layers for map visualization.

cURL Example

curl -X POST "https://your-atlasomi-instance.com/api/v2/designs/render" \
  -H "Content-Type: application/json" \
  -d '{
    "design_id": "123e4567-e89b-12d3-a456-426614174000",
    "layers": ["Fiber Routes", "Network Nodes"],
    "simplified": true
  }'

Complete cURL Workflows

Basic Data Extraction Workflow

# Step 1: Validate your AOI
curl -X POST "https://your-atlasomi-instance.com/api/v2/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "aoi_boundary": {
      "type": "Polygon",
      "coordinates": [[[36.8219, -1.2921], [36.8250, -1.2921], [36.8250, -1.2950], [36.8219, -1.2950], [36.8219, -1.2921]]]
    }
  }'

# Step 2: Extract data from multiple sources
curl -X POST "https://your-atlasomi-instance.com/api/v2/extract" \
  -H "Content-Type: application/json" \
  -d '{
    "aoi_boundary": {
      "type": "Polygon",
      "coordinates": [[[36.8219, -1.2921], [36.8250, -1.2921], [36.8250, -1.2950], [36.8219, -1.2950], [36.8219, -1.2921]]]
    },
    "sources": {
      "microsoft_buildings": {"enabled": true, "timeout": 30},
      "google_buildings": {"enabled": true, "timeout": 30},
      "osm_roads": {"enabled": true, "timeout": 25},
      "osm_landmarks": {"enabled": true, "timeout": 25}
    }
  }' \
  -o response.json

# Step 3: Extract job_id from response and download results
JOB_ID=$(cat response.json | grep -o '"job_id":"[^"]*' | cut -d'"' -f4)

# Download as KMZ (recommended for Google Earth)
curl -X GET "https://your-atlasomi-instance.com/api/v2/download/$JOB_ID/kmz" \
  -o "extracted_data.kmz"

Design Upload and Rendering Workflow

# Step 1: Upload design file
curl -X POST "https://your-atlasomi-instance.com/api/v2/designs/upload" \
  -F "file=@my_network_design.kml" \
  -o upload_response.json

# Step 2: Extract design_id from response
DESIGN_ID=$(cat upload_response.json | grep -o '"design_id":"[^"]*' | cut -d'"' -f4)

# Step 3: Render specific layers on map
curl -X POST "https://your-atlasomi-instance.com/api/v2/designs/render" \
  -H "Content-Type: application/json" \
  -d "{
    \"design_id\": \"$DESIGN_ID\",
    \"layers\": [\"Fiber Routes\", \"Network Nodes\"],
    \"simplified\": true
  }" \
  -o render_response.json

Python Examples

Basic Data Extraction

import requests
import json

# Configuration
BASE_URL = "https://your-atlasomi-instance.com/api/v2"

# Define area of interest (Nairobi, Kenya example)
aoi_polygon = {
    "type": "Polygon",
    "coordinates": [[
        [36.8219, -1.2921],
        [36.8250, -1.2921], 
        [36.8250, -1.2950],
        [36.8219, -1.2950],
        [36.8219, -1.2921]
    ]]
}

# Configure data sources
sources = {
    "microsoft_buildings": {"enabled": True, "timeout": 30},
    "osm_roads": {"enabled": True, "timeout": 25},
    "osm_landmarks": {"enabled": True, "timeout": 25}
}

# Make extraction request
response = requests.post(
    f"{BASE_URL}/extract",
    json={
        "aoi_boundary": aoi_polygon,
        "sources": sources
    }
)

if response.status_code == 200:
    result = response.json()
    job_id = result["job_id"]
    print(f"Extraction started: {job_id}")
    
    # Download results
    download_response = requests.get(
        f"{BASE_URL}/download/{job_id}/geojson"
    )
    
    if download_response.status_code == 200:
        with open("extracted_data.geojson", "wb") as f:
            f.write(download_response.content)
        print("Data downloaded successfully!")
else:
    print(f"Error: {response.status_code} - {response.text}")

Design Upload Example

import requests

BASE_URL = "https://your-atlasomi-instance.com/api/v2"

# Upload design file
with open("network_design.kml", "rb") as f:
    files = {"file": f}
    response = requests.post(f"{BASE_URL}/designs/upload", files=files)

if response.status_code == 200:
    result = response.json()
    design_id = result["design_id"]
    print(f"Design uploaded: {design_id}")
    
    # Render design on map
    render_response = requests.post(
        f"{BASE_URL}/designs/render",
        json={
            "design_id": design_id,
            "layers": ["Fiber Routes", "Network Nodes"],
            "simplified": True
        }
    )
    
    if render_response.status_code == 200:
        render_data = render_response.json()
        print(f"Rendered {render_data['total_features']} features")
else:
    print(f"Upload failed: {response.status_code}")