Urban Lens

Plataforma de análise urbana e geoespacial para explorar características de localidades no Rio de Janeiro. O sistema combina dados de mobilidade, pontos de interesse, vulnerabilidade social e segurança pública em uma interface cartográfica interativa.

O projeto foi desenvolvido como base experimental para um artigo científico acadêmico, integrando diferentes fontes públicas e técnicas de processamento espacial.

Destaques técnicos

• Consultas geoespaciais com PostgreSQL e PostGIS
• Geocodificação de endereços por meio do Nominatim/OpenStreetMap
• Busca de pontos de interesse e transportes por coordenada e raio
• Mapeamento de áreas de vulnerabilidade social com polígonos GeoJSON
• Análise de estatísticas criminais por Circunscrição Integrada de Segurança Pública (CISP)
• Importação e tratamento de dados GeoJSON, JSON e CSV
• Índices espaciais criados por migrações TypeORM
• Backend modular com NestJS e TypeORM
• Mapa interativo com React, Leaflet e React Leaflet
• Infraestrutura local com Docker Compose, PostgreSQL/PostGIS e Nominatim

Tecnologias

Backend

• Node.js
• TypeScript
• NestJS 11
• TypeORM
• PostgreSQL 15
• PostGIS 3.4
• Axios
• Jest e Supertest

Frontend

• React 19
• TypeScript
• Vite
• Leaflet e React Leaflet
• Axios
• Sass

Infraestrutura e dados

• Docker e Docker Compose
• Nominatim
• OpenStreetMap
• GeoJSON e CSV

Problema investigado

Informações urbanas importantes normalmente estão distribuídas entre diferentes bases e formatos. O Urban Lens reúne esses dados em uma única experiência de consulta, permitindo analisar uma localidade por diferentes dimensões:

• disponibilidade de transporte público;
• pontos de interesse próximos;
• presença de áreas de vulnerabilidade social;
• indicadores de segurança por região.

O resultado é apresentado em um mapa interativo, facilitando a interpretação espacial das informações.

Funcionalidades

Busca e geocodificação

• Busca de endereços em texto livre ou por campos estruturados
• Paginação dos resultados de geocodificação
• Conversão de endereços em latitude e longitude por Nominatim
• Restrição das buscas ao Brasil

Pontos de interesse

• Consulta de estabelecimentos próximos por coordenada
• Filtro por categoria
• Paginação e raio de busca configurável
• Agrupamento de categorias para apresentação no frontend

Transporte

• Busca de infraestrutura de transporte próxima
• Consultas espaciais por latitude, longitude e raio
• Paginação dos resultados

Vulnerabilidade social

• Identificação da área correspondente a uma coordenada
• Consulta de áreas vulneráveis próximas
• Visualização de polígonos no mapa
• Importação de dados geográficos por migrações

Segurança pública

• Localização da CISP correspondente a uma coordenada
• Consulta e cálculo de indicadores criminais da região
• Importação de áreas CISP em JSON/GeoJSON
• Importação de estatísticas do ISP-RJ em CSV

Arquitetura

flowchart LR
    User[Usuário] --> Frontend[React + Leaflet]
    Frontend -->|HTTP| API[API NestJS]

    API --> Geocode[Módulo Geocode]
    API --> Places[Módulo Places]
    API --> Transport[Módulo Transports]
    API --> Vulnerability[Módulo Vulnerability]
    API --> Crime[Módulo Criminal Statistics]

    Geocode --> Nominatim[Nominatim]
    Places --> PostGIS[(PostgreSQL + PostGIS)]
    Transport --> PostGIS
    Vulnerability --> PostGIS
    Crime --> PostGIS
    Nominatim --> OSM[OpenStreetMap]

Loading

Módulos do backend

Módulo	Responsabilidade
geocode	Busca e geocodificação de endereços via Nominatim
places	Pontos de interesse, categorias e agrupamentos
transports	Infraestrutura de transporte próxima
vulnerability	Áreas e indicadores de vulnerabilidade social
criminal-statistic	Áreas CISP e estatísticas de segurança pública

Fontes de dados

O projeto utiliza dados provenientes de fontes públicas:

• OpenStreetMap (OSM): vias, transportes e pontos de interesse;
• Nominatim: busca e geocodificação;
• Instituto Pereira Passos (IPP): limites de áreas de vulnerabilidade/favelas;
• Instituto de Segurança Pública do Rio de Janeiro (ISP-RJ): estatísticas criminais;
• IBGE: referência para dados territoriais e demográficos usados no contexto da pesquisa.

Os arquivos versionados para importação ficam em backend/src/data/.

Estrutura do projeto

urban-lens/
├── backend/
│   ├── scripts/                    # Scripts de manutenção de dados
│   └── src/
│       ├── data/                   # Arquivos GeoJSON, JSON e CSV
│       ├── database/
│       │   ├── migrations/         # Migrações e importações TypeORM
│       │   └── typeorm.config.ts
│       └── modules/
│           ├── criminal-statistic/
│           ├── geocode/
│           ├── places/
│           ├── transports/
│           └── vulnerability/
├── frontend/
│   └── urban-lens/
│       └── src/
│           ├── components/
│           ├── hooks/
│           ├── services/
│           ├── styles/
│           ├── types/
│           └── utils/
└── infra/
    ├── docker/
    │   └── docker-compose.yml
    └── scripts/

Como executar

Pré-requisitos

• Git
• Node.js 18 ou superior
• npm 9 ou superior
• Docker
• Docker Compose

1. Clonar o repositório

git clone https://github.com/levyath/urban-lens.git
cd urban-lens

2. Preparar os dados do OpenStreetMap

O Nominatim configurado no Compose espera um arquivo PBF chamado:

infra/maps/sudeste-260306.osm.pbf

Crie a pasta infra/maps e coloque nela um extrato .osm.pbf compatível. Arquivos PBF não são versionados devido ao tamanho.

Caso utilize outro nome de arquivo, altere PBF_PATH em infra/docker/docker-compose.yml.

3. Iniciar PostgreSQL/PostGIS e Nominatim

cd infra/docker
docker compose up -d

Verifique o estado dos serviços:

docker compose ps
docker compose logs -f nominatim

Na primeira execução, a importação dos dados do OpenStreetMap pode levar vários minutos, dependendo do tamanho do arquivo e dos recursos disponíveis.

4. Configurar e executar o backend

Na pasta backend, crie um arquivo .env:

PORT=3000
DB_HOST_DB=localhost
DB_PORT_DB=5432
DB_USER=osm
DB_PASSWORD=osm
DB_DATABASE_DB=osm
NOMINATIM_URL=http://localhost:8080

Instale as dependências e execute as migrações:

cd backend
npm install
npm run migration:run
npm run start:dev

O backend ficará disponível em http://localhost:3000.

As migrações:

• habilitam a extensão PostGIS;
• criam índices espaciais para as tabelas OSM;
• criam as tabelas de vulnerabilidade e CISP;
• importam dados geográficos e estatísticas versionados no projeto.

5. Configurar e executar o frontend

Na pasta frontend/urban-lens, crie um arquivo .env:

VITE_API_URL=http://localhost:3000

Depois execute:

cd frontend/urban-lens
npm install
npm run dev

O frontend ficará disponível em http://localhost:5173.

Endpoints principais

Método	Endpoint	Descrição
GET	/geocode	Busca e geocodificação de endereços
GET	/places/near	Lista pontos de interesse próximos
GET	/places/categories	Lista categorias de lugares
GET	/places/clusters	Retorna agrupamentos de lugares
GET	/transports/near	Lista transportes próximos
GET	/vulnerability	Avalia a vulnerabilidade de uma coordenada
GET	/vulnerability/near	Lista áreas vulneráveis próximas
GET	/cisp-statistic/local	Analisa estatísticas criminais por coordenada
POST	/cisp-statistic/importar	Importa estatísticas do arquivo CSV
POST	/cisp-area/importar	Importa as áreas CISP

Exemplo de consulta

curl "http://localhost:3000/places/near?lat=-22.9068&lon=-43.1729&radius=1000&page=1&page_size=20"

Testes e qualidade

Backend

cd backend
npm run test
npm run test:e2e
npm run test:cov
npm run lint

Frontend

cd frontend/urban-lens
npm run lint
npm run build

Migrações

Executar todas as migrações pendentes:

cd backend
npm run migration:run

Reverter a última migração:

npm run migration:revert

Contexto acadêmico

O Urban Lens foi desenvolvido para apoiar um artigo científico acadêmico sobre análise urbana orientada por dados. A aplicação funciona como prova de conceito para integração, processamento e visualização de informações públicas heterogêneas.

Os resultados apresentados devem ser interpretados no contexto experimental do trabalho. Indicadores de vulnerabilidade e segurança não devem ser utilizados isoladamente para decisões sobre pessoas ou comunidades.

Autores

• Alex Cordeiro
• Levyath

Consulte também o histórico de contribuidores.

Agradecimentos

• OpenStreetMap e comunidade OSM
• Instituto Pereira Passos
• Instituto de Segurança Pública do Rio de Janeiro
• IBGE
• CEFET/RJ