nmaipy 4.0.2

Nearmap AI Python Library for extracting AI features from aerial imagery

nmaipy - Nearmap AI Python Library

Extract building footprints, vegetation, damage assessments, and other AI features from Nearmap's aerial imagery using simple Python code.

What is nmaipy?

nmaipy (pronounced "en-my-pie") is a Python library that makes it easy for data scientists to access Nearmap's AI-powered geospatial data. Whether you're analyzing a few properties or processing millions of buildings across entire cities, nmaipy handles the complexity so you can focus on your analysis.

Quick Start for Data Scientists

1. Install

Option A: Using pip

pip install -e .

Option B: Using conda

Minimal installation (core features only):

conda env create -f environment-minimal.yaml
conda activate nmaipy

Full installation (includes development and notebook tools):

conda env create -f environment.yaml
conda activate nmaipy

Option C: Install into existing conda environment

conda install -c conda-forge geopandas pandas numpy pyarrow psutil pyproj python-dotenv requests rtree shapely stringcase tqdm
pip install -e .

Additional options

For running notebooks with pip:

pip install -e ".[notebooks]"

For development with pip:

pip install -e ".[dev]"

2. Set your API key

export API_KEY=your_api_key_here

3. Run your first extraction

from nmaipy.exporter import NearmapAIExporter

# Extract building and vegetation data
exporter = NearmapAIExporter(
    aoi_file='my_parcels.geojson',  # Your areas of interest
    output_dir='results',            # Where to save outputs
    country='au',                     # au, us, nz, or ca
    packs=['building', 'vegetation'], # What features to extract
    processes=4                       # Parallel processing
)

exporter.run()

That's it! Your results will be saved as CSV or Parquet files in the output directory.

Note: AOIExporter is available as a backward-compatible alias for NearmapAIExporter.

Common Use Cases

🏢 Urban Planning

Extract comprehensive data about buildings, vegetation coverage, and surface materials:

exporter = NearmapAIExporter(
    aoi_file='city_blocks.geojson',
    output_dir='urban_analysis',
    country='au',
    packs=['building', 'vegetation', 'surfaces', 'solar'],
    save_features=True,  # Get individual features, not just summaries
    include_parcel_geometry=True  # Keep boundaries for GIS analysis
)

🌊 Disaster Response

Assess damage after natural disasters like hurricanes or floods:

exporter = NearmapAIExporter(
    aoi_file='affected_areas.geojson',
    output_dir='damage_assessment',
    country='us',
    packs=['damage'],
    since='2024-07-08',  # Date range of the event
    until='2024-07-11',
    rapid=True,  # Use rapid post-catastrophe imagery
    save_features=True
)

🌳 Environmental Analysis

Study vegetation coverage and tree canopy:

exporter = NearmapAIExporter(
    aoi_file='study_area.geojson',
    output_dir='vegetation_study',
    country='au',
    packs=['vegetation'],
    save_features=True  # Get individual tree polygons
)

🏊 Market Research

Find properties with pools or solar panels:

exporter = NearmapAIExporter(
    aoi_file='suburbs.geojson',
    output_dir='market_analysis',
    country='au',
    packs=['pools', 'solar'],
    include_parcel_geometry=True
)

🏠 Roof Age Analysis (US Only)

Predict roof installation dates using AI analysis of historical imagery.

Unified approach (recommended) - combines Feature API and Roof Age in one export:

exporter = NearmapAIExporter(
    aoi_file='properties.geojson',
    output_dir='unified_results',
    country='us',
    packs=['building'],
    roof_age=True,  # Include Roof Age API data
    save_features=True
)
exporter.run()

Standalone approach - for roof age data only:

from nmaipy.roof_age_exporter import RoofAgeExporter

exporter = RoofAgeExporter(
    aoi_file='properties.geojson',
    output_dir='roof_age_results',
    country='us',
    threads=10,
    output_format='both'  # Generate both GeoParquet and CSV
)
exporter.run()

The Roof Age API uses machine learning to analyze multiple imagery captures over time, combined with building permit data and climate information, to predict when roofs were last installed or significantly renovated. Each roof feature includes:

• Predicted installation date
• Confidence score (trust score)
• Evidence type and number of captures analyzed
• Timeline of all imagery used in analysis

This is valuable for:

• Insurance underwriting and risk assessment
• Property valuation and market analysis
• Maintenance planning and capital budgeting
• Real estate due diligence

Available AI Features

Some of the more common AI packs are below - there are more and growing, available via API request or on the Nearmap help.nearmap.com page.

Pack	Description	Example Use Cases
building	Building footprints and heights	Urban planning, property analysis
vegetation	Trees and vegetation coverage	Environmental studies, urban forestry
surfaces	Ground surface materials	Permeability studies, heat mapping
pools	Swimming pool detection	Compliance, market research
solar	Solar panel detection	Renewable energy assessment
damage	Post-disaster damage classification	Insurance, emergency response
building_characteristics	Detailed roof types, materials	Detailed property analysis

Input Data Formats

nmaipy accepts areas of interest (AOIs) in several formats:

• GeoJSON: Standard geospatial format with polygons
• Parquet: Efficient columnar format for large datasets
• CSV: Simple format with lat/lon coordinates or WKT geometries

Your input file should contain polygon geometries representing the areas you want to analyze (parcels, census blocks, suburbs, etc.).

Output Data

Results are saved as CSV or Parquet files containing:

• Rollups: Summary statistics per AOI (counts, areas, percentages)
• Features: Individual AI features with geometries (when save_features=True)
• Metadata: Survey dates, data quality metrics

Examples

Quick start: See run_10_test.py for a minimal working example with property-based exports:

export API_KEY=your_api_key_here
python run_10_test.py

More examples: Check out examples.py for complete working examples of different use cases.

Unified export: See run.py for a full example combining Feature API and Roof Age API.

Working with Large Areas

nmaipy automatically handles large areas by:

• Splitting them into manageable grid cells
• Processing in parallel
• Combining results seamlessly

For areas larger than 1 sq km, the library will automatically use gridding:

exporter = NearmapAIExporter(
    aoi_file='large_region.geojson',
    output_dir='large_area_results',
    country='us',
    packs=['building'],
    aoi_grid_inexact=True,  # Allow mixing survey dates if needed
    processes=16  # Use more processes for speed
)

Performance Tips

1. Use parallel processing: Set processes to the number of CPU cores
2. Process in chunks: Use chunk_size for very large datasets
3. Cache results: Reuse cached API responses with cache_dir
4. Filter by date: Use since and until to get specific time periods

Command Line Interface

nmaipy can be run from the command line:

python nmaipy/exporter.py \
    --aoi-file "parcels.geojson" \
    --output-dir "results" \
    --country us \
    --packs building vegetation \
    --save-features \
    --roof-age  # Include Roof Age API data (US only)

Key CLI options:

• --roof-age: Include Roof Age API data (US only)
• --save-features: Save per-class GeoParquet files with feature geometries
• --aoi-grid-cell-size: Grid cell size for large AOIs (default: ~200m)
• --max-retries: Maximum API retry attempts
• --primary-decision: Feature selection method (largest_intersection, nearest, optimal)

Run python nmaipy/exporter.py --help for all options.

Getting Help

• Examples: See examples.py for common use cases
• Notebooks: Check the notebooks/ directory for Jupyter notebook tutorials
• Issues: Report bugs or request features on GitHub

Requirements

• Python 3.11+
• Nearmap API key (contact Nearmap for access)
• 4GB+ RAM recommended for large extractions

Advanced: Building a Conda Package

For system administrators who want to create a local conda package:

conda build conda.recipe
conda install --use-local nmaipy

This will create a conda package that can be shared internally or uploaded to a conda channel.

License

See LICENSE file for details.