Unicef Geospatial Project

This project is a collection of tools and scripts for working with geospatial data and AI. The objective is to research and develop tools for interacting with geospatial data using natural language.

Architecture

Demo

Screen.Recording.2025-02-07.at.16.13.26.online-video-cutter.com.mp4

Installing dependencies

The project API dependencies are managed using uv, while the frontend dependencies are managed via npm.

To install the API dependencies:

uv sync

To install the frontend dependencies:

cd unicef-frontend
npm install

In order to run the project it's also needed the gcloud CLI

Running the project

To run the project the API:

uv run python unicef_geospatial/app.py

This will start a local server at http://127.0.0.1:8000/.

To run the frontend:

cd unicef-frontend
npm run dev

This will start a local server at http://127.0.0.1:5173.

Secrets

The project uses python-dotenv to load environment variables from a .env file.

To copy the .env.example file to a new file called .env:

cp .env.example .env

The .env file should be located in the root of the project and contain the following variables:

• OPENAI_API_KEY: The API key for OpenAI.
• MODEL_NAME: The name of the OpenAI model to use.
• LANGFUSE_PUBLIC_KEY: The public key for the langfuse cloud.
• LANGFUSE_SECRET_KEY: The secret key for the langfuse cloud.
• LANGFUSE_HOST: The host URL for the langfuse cloud.
• LANGFUSE_PROJECT_ID: The project id for the langfuse cloud.

For authentication into the google earth engine, you need a service account and download the credentials file. The file should be named ee_auth.json and placed in the root of the project. It should look like this:

{
    "type": "service_account",
    "project_id": "XXX",
    "private_key_id": "XXX",
    "private_key": "XXX",
    "client_email": "XXX",
    "client_id": "XXX",
    "auth_uri": "XXX",
    "token_uri": "XXX",
    "auth_provider_x509_cert_url": "XXX",
    "client_x509_cert_url": "XXX",
    "universe_domain": "XXX"
}

Accessing the logs

The logs are stored in langfuse cloud. They are accesible here.

Project structure

• unicef_geospatial/: The main project for working with geospatial data.

  • agent/: Functions for creating and running langchain agents.
  • data_warehouse/: Tools and functions for interacting with the unicef data warehouse.
  • earth_engine/: Functions for interacting with google earth engine.
  • geospatial/: Tools and functions for interacting with geospatial data.
  • utils/: Utility functions for the project.
  • app.py: The main entry point for the API.

• unicef-frontend/: The frontend for the project.

• notebooks/: Notebooks with interactive visualizations and demonstrations.

• research/: Research scripts for exploring geospatial data, unicef api, etc.

Notebooks

• interactive_map.ipynb: Ask questions in natural language about heatwave data.

Research

• api_research.py: Research on the unicef api, transform the sdmx-json to pandas dataframe.
• ee_upload_images.py: Upload heatwave data to google earth engine.
• initial_research.py: Research on how to use langchain agents to interact with a dataframe.
• interact_geospatial.py: Research on how to use langchain agents to interact with a geospatial data.
• pandas_ai.py: Research on how to use pandas-ai to interact with a unicef dataframe.
• unicef_geospatial_ee.py: Research on how to use google earth engine to interact with a geospatial data, creating an interactive map.