Teknik API Referansı

Bu sayfa, mapindata kütüphanesi altındaki sınıf ve fonksiyonların teknik parametrelerini kaynak kodundaki docstring'lerden otomatik olarak listeler.

---

Core — Yapılandırma ve Zaman Araçları

Ortam değişkenlerinden SDK konfigürasyonunu yönetir.

Kullanım

cfg = ConfigManager() print(cfg.sparkMaster) # local[8] print(cfg.sparkDriverMemory) # 24g (otomatik) print(cfg.s3Bucket) # mapindata-prod print(cfg.radiusMeters) # 15

Ortam değişkenleri .env dosyasından ya da sistem env'inden okunur. Zorunlu alan eksikse ValueError fırlatılır.

dbConnectionString: str property

SQLAlchemy formatında bağlantı dizesi.

googlePlacesApiKey: str property

Google Places API (New) anahtarı. GOOGLE_PLACES_API_KEY env değişkeninden okunur.

radiusMeters: int property

Varsayılan Haversine yarıçapı (metre). MAPIN_RADIUS_METERS ile override edilebilir.

sparkCores: int property

Kullanılacak CPU çekirdek sayısı. SPARK_EXECUTOR_CORES yoksa tüm çekirdekler.

sparkDefaultParallelism: int property

spark.default.parallelism = çekirdek sayısı × 10

sparkDriverMemory: str property

Driver belleği. SPARK_DRIVER_MEMORY yoksa sistem RAM'inin %75'i.

sparkExecutorMemory: str property

Executor belleği. SPARK_EXECUTOR_MEMORY yoksa sparkDriverMemory ile aynı.

sparkJars: str property

S3A erişimi için gerekli JAR dosyaları. SPARK_JARS env değişkeninden okunur.

sparkMaster: str property

Spark master URL. Örn: local[8]

sparkShufflePartitions: int property

spark.sql.shuffle.partitions = sparkDefaultParallelism ile senkron

testProvince: str property

Test ve geliştirme için varsayılan il. MAPIN_TEST_PROVINCE ile override edilebilir.

mobilityDataPath(province: str) -> str

Verilen il için V2 H3 zenginleştirilmiş Parquet veri yolunu döndürür.

Suffix MAPIN_MOBILITY_DATA_SUFFIX env var ile override edilebilir. Varsayılan suffix tüm iller için: v2_h3_alt_rowsorted (repartitionByRange(N, h3_res9_id) + sortWithinPartitions(h3_res9_id) + snappy + 64MB block)

Parameters:

Name	Type	Description	Default
province	str	İl adı (büyük/küçük harf duyarsız, örn. "Istanbul" → "istanbul")	required

Returns:

Type	Description
str	S3A uyumlu tam yol (str)

mobilitySparkConfig(appName: str = 'MapinDataMobility') -> dict

Büyük ölçekli mobil veri işleme için optimize edilmiş Spark konfigürasyon sözlüğü.

Bellek ve paralellik ayarları ConfigManager'dan dinamik gelir. S3A bağlantı ayarları sabit fakat prod ortamında environment variable ile override edilebilir.

Kullanım

cfg = ConfigManager() for key, val in cfg.mobilitySparkConfig("FootfallJob").items(): builder = builder.config(key, val)

Returns:

Type	Description
dict	dict — SparkSession.builder.config(key, value) çiftleri

Period string'ini (bitiş, başlangıç) datetime tuple'ına dönüştürür.

Parameters:

Name	Type	Description	Default
period	str	"30d", "90d", "24h" vb. Birim: d = gün, h = saat.	required
referenceTime	Optional[datetime]	Hesaplama için referans "şimdi" zamanı (UTC). None ise datetime.datetime.utcnow() kullanılır.	None

Returns:

Type	Description
tuple[datetime, datetime]	(start, end) tuple'ı — her ikisi de UTC naive datetime.

Raises:

Type	Description
ValueError	Geçersiz period formatı.

Verilen saatin hangi zaman dilimine düştüğünü döndürür.

Parameters:

Name	Type	Description	Default
hour	int	0–23 arası tam sayı (UTC saat).	required

Returns:

Type	Description
str	TIME_SEGMENTS anahtarlarından biri: "morning", "afternoon",
str	"late_day", "prime_time" veya "night".

Raises:

Type	Description
ValueError	hour 0–23 aralığı dışındaysa.

Zaman dilimi adını başlangıç–bitiş saat etiketi olarak formatlar.

Örnek: "morning" → "morning_07_11"

Parameters:

Name	Type	Description	Default
segment	str	TIME_SEGMENTS anahtarı.	required

Returns:

Type	Description
str	"segment_SS_EE" formatında string.

Raises:

Type	Description
KeyError	Bilinmeyen segment adı.

---

Coğrafi Yardımcılar

İki koordinat arasındaki yüzey mesafesini metre cinsinden hesaplar.

Haversine formülü kullanır; kısa mesafeler için yeterince doğrudur. GeoJSON koordinat sırası olan (lon, lat) yerine burada (lat, lon) kullanılır.

Parameters:

Name	Type	Description	Default
lat1	float	Birinci noktanın enlemi (derece)	required
lon1	float	Birinci noktanın boylamı (derece)	required
lat2	float	İkinci noktanın enlemi (derece)	required
lon2	float	İkinci noktanın boylamı (derece)	required

Returns:

Type	Description
float	Mesafe (metre)

Verilen koordinatın H3 hücresini 64-bit tam sayı olarak döndürür.

Parquet dosyalarında h3_res9_id INT64 olarak saklandığından bu çıktı doğrudan Spark filter ifadelerinde kullanılabilir.

Parameters:

Name	Type	Description	Default
lat	float	Enlem	required
lon	float	Boylam	required
res	int	H3 çözünürlük (varsayılan 9)	9

Returns:

Type	Description
int	H3 hücre indeksi (int64).

Raises:

Type	Description
ImportError	h3 kurulu değilse

GeoJSON Polygon için H3 hücrelerini INT64 listesi olarak döndürür.

Önce polyfill uygular; ardından sınır hücrelerine kring(bufferK) tamponu ekler. Büyük / orta polygonlar (alan ≥ 100 000 m²) için uygundur.

Polyfill sonucu boşsa (küçük polygon, < 1 H3 hücresi) boş liste döner — bu durumda h3CentroidCell + grid_disk kullanın.

Parameters:

Name	Type	Description	Default
polygonCoords	list	GeoJSON Polygon coordinates [ [[lon, lat], ...] ]	required
res	int	H3 çözünürlük (varsayılan 9)	9
bufferK	int	Kenar tamponu halka sayısı (varsayılan 1)	1

Returns:

Type	Description
list	H3 hücre INT64 listesi.

Raises:

Type	Description
ImportError	h3 kurulu değilse

---

Veri İstemcileri

PostgreSQL bağlantı yöneticisi.

SQLAlchemy Engine üzerine kurulu; connection pool, sorgu çalıştırma ve pandas DataFrame okuma işlevlerini sağlar.

Bağlantı bilgileri ConfigManager üzerinden env'den okunur: MAPIN_DB_HOST, MAPIN_DB_PORT, MAPIN_DB_NAME, MAPIN_DB_USER, MAPIN_DB_PASSWORD, MAPIN_DB_POOL_SIZE (varsayılan 5), MAPIN_DB_MAX_OVERFLOW (varsayılan 10)

Kullanım

cfg = ConfigManager() db = PgClient(cfg) db.ping() # bağlantı testi df = db.readSql("SELECT * FROM locations LIMIT 10") with db.session() as ses: ses.execute(text("SELECT 1")) db.dispose()

dispose() -> None

Connection pool'u kapatır ve engine'i serbest bırakır.

engine() -> Engine

SQLAlchemy Engine'i başlatır; zaten varsa mevcut engine'i döndürür.

Pool boyutu MAPIN_DB_POOL_SIZE (varsayılan 5), taşma limiti MAPIN_DB_MAX_OVERFLOW (varsayılan 10). pre_ping=True ile stale bağlantılar otomatik temizlenir.

execute(sql: str, params: dict | None = None) -> None

DDL / DML sorgularını çalıştırır ve commit eder (SELECT dışı işlemler).

Parameters:

Name	Type	Description	Default
sql	str	Çalıştırılacak SQL	required
params	dict | None	Parametre sözlüğü	None

getMapinDataByCoordinate(lat: float, lon: float, radiusMeters: float | None = 50.0, limit: int = 5) -> pd.DataFrame

Verilen koordinata en yakın müşteri noktalarını cleaned.mapin_data tablosundan döndürür.

PostGIS ST_DWithin + ST_Distance (geography cast) kullanır. Tüm kullanıcı girdileri bound parameter olarak iletilir.

Parameters:

Name	Type	Description	Default
lat	float	Enlem (WGS-84)	required
lon	float	Boylam (WGS-84)	required
radiusMeters	float | None	Arama yarıçapı (metre). None verilirse limit kadar en yakın kayıt döner.	50.0
limit	int	Maksimum sonuç sayısı (varsayılan 5).	5

Returns:

Type	Description
DataFrame	pd.DataFrame — kolonlar: id, customer_id, title, city, district, lat, lon, mapin_segmentation, mapin_profile_score, distance_m

Örnek

df = db.getMapinDataByCoordinate(41.0370, 28.9850, radiusMeters=200)

getPoiByCoordinate(lat: float, lon: float, radiusMeters: float | None = 50.0, limit: int = 5, onlyActive: bool = True) -> pd.DataFrame

Verilen koordinata en yakın POI'leri master.poi tablosundan döndürür.

PostGIS ST_DWithin + ST_Distance (geography cast) kullanır; mesafe hesabı küresel (metre cinsinden doğru). Tüm kullanıcı girdileri SQLAlchemy bound parameter olarak iletilir — SQL injection riski yoktur.

Parameters:

Name	Type	Description	Default
lat	float	Enlem (WGS-84)	required
lon	float	Boylam (WGS-84)	required
radiusMeters	float | None	Arama yarıçapı (metre). None verilirse limit kadar en yakın POI döner, yarıçap kısıtı uygulanmaz.	50.0
limit	int	Maksimum sonuç sayısı (varsayılan 5).	5
onlyActive	bool	True ise yalnızca is_active=true kayıtlar gelir.	True

Returns:

Type	Description
DataFrame	pd.DataFrame — kolonlar: mapin_id, name, lat, lon, category, district_code, neighborhood_code, is_active, distance_m

Örnek

df = db.getPoiByCoordinate(41.0370, 28.9850, radiusMeters=100) df = db.getPoiByCoordinate(41.0370, 28.9850, radiusMeters=None, limit=10)

ping() -> bool

Veritabanına bağlanıp SELECT 1 çalıştırır.

Returns:

Type	Description
bool	True — bağlantı başarılı
bool	False — bağlantı başarısız (hata mesajı yazdırılır)

readSql(sql: str, params: dict | None = None) -> pd.DataFrame

SQL sorgusu çalıştırır ve sonucu pandas DataFrame olarak döndürür.

Parameters:

Name	Type	Description	Default
sql	str	Çalıştırılacak SQL (parametre için :isim sözdizimi kullanın)	required
params	dict | None	Parametre sözlüğü — {"isim": değer}	None

Returns:

Type	Description
DataFrame	pd.DataFrame

Örnek

df = db.readSql( "SELECT * FROM devices WHERE province = :prov", {"prov": "istanbul"} )

session() -> Generator[Session, None, None]

ORM oturumu sağlar; hata durumunda rollback yapar.

Kullanım

with db.session() as ses: ses.add(some_orm_object)

DuckDB bağlantısı ve S3 yol yönetimi.

S3 kimlik doğrulaması boto3 DefaultCredentialChain üzerinden yapılır (EC2 IAM Role veya env var — AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY).

Başlatma sırası

1. Bellek içi DuckDB bağlantısı oluştur
2. httpfs + spatial extension kur / yükle
3. AWS kimlik bilgilerini boto3'ten al, DuckDB'ye aktar
4. Thread sayısını ConfigManager.sparkCores üzerinden ayarla

Kullanım

cfg = ConfigManager() client = DuckDBClient(cfg) con = client.connect() path = client.s3Path("istanbul")

con ve path → FootfallEngine(con=con, s3Path=path)

close() -> None

DuckDB bağlantısını kapatır ve dahili referansı temizler.

connect() -> duckdb.DuckDBPyConnection

DuckDB bağlantısını başlatır; zaten açıksa mevcut bağlantıyı döndürür.

Yapılanlar

• httpfs extension: S3 okuma desteği
• spatial extension: ST_Contains / ST_GeomFromGeoJSON coğrafi sorgular
• boto3 DefaultCredentialChain → DuckDB S3 kimlik aktarımı
• Thread sayısı → ConfigManager.sparkCores (tek makinede optimum parallelik)

Returns:

Type	Description
DuckDBPyConnection	duckdb.DuckDBPyConnection

s3Path(province: str) -> str

Verilen il için DuckDB-uyumlu S3 glob yolunu döndürür.

mobilityDataPath s3a:// şemasıyla döner; DuckDB httpfs s3:// bekler. Bu metod şema dönüşümünü ve *.parquet glob eklemesini otomatik yapar.

Parameters:

Name	Type	Description	Default
province	str	İl adı (örn. "istanbul", "Istanbul")	required

Returns:

Type	Description
str	str — s3://bucket/prefix/province/suffix/*.parquet

MapinData S3 veri deposundan PySpark ile veri okur.

Kullanım (temel): cfg = ConfigManager() client = S3Client(cfg) spark = client.createSession("FootfallJob") df = client.loadMobilityData(province="Istanbul")

Kullanım (özel yol): df = client.loadData("s3a://mapindata-raw-data/echo_data_partitioned/province=Istanbul/")

Spark oturumu singleton olarak yönetilir; aynı process içinde createSession tekrar çağrılırsa mevcut oturum döndürülür (SparkSession.builder.getOrCreate davranışı).

spark property

Mevcut ya da yeni bir Spark oturumu döndürür (lazy).

createSession(appName: str = 'MapinDataMobility') -> object

Mobil veri için optimize edilmiş Spark oturumu oluşturur ve döndürür.

ConfigManager.mobilitySparkConfig() üzerinden dinamik bellek/paralellik ayarlarını otomatik alır. SPARK_JARS tanımlıysa S3A JAR'ları da eklenir.

Parameters:

Name	Type	Description	Default
appName	str	Spark UI'da görünecek uygulama adı	'MapinDataMobility'

Returns:

Type	Description
object	SparkSession

loadCleanMobilityData(province: str, columns: list[str] | None = None) -> object

MapinData V2 H3 zenginleştirilmiş temiz veri yükler.

V2 veri seti: repartitionByRange(h3_res9_id, device_aid) ile S3'e yazılmış; h3_res9_id üzerinde Parquet row-group skip, footfall sorgularını ~14× hızlandırır. FootfallEngine Spark metodlarının önerilen girdi kaynağıdır.

Desteklenen iller: istanbul, ankara, izmir, antalya, mugla — ve v2_h3_alt_rowsorted formatında üretilmiş tüm iller (ConfigManager.mobilityDataPath ile)

Parameters:

Name	Type	Description	Default
province	str	İl adı (örn. "Istanbul", “istanbul”)	required
columns	list[str] | None	Okunacak sütun listesi. None → MOBILITY_CLEAN_COLUMNS (timestamp, device_aid, lat, lon, hacc, neighborhood, h3_res9_id)	None

Returns:

Type	Description
object	pyspark.sql.DataFrame — V2 H3 sıralanmış temiz mobil veri

loadData(s3Path: str, basePath: str | None = None, format: str = 'parquet', columns: list[str] | None = None) -> object

S3'teki herhangi bir dosyayı Spark DataFrame olarak okur.

Parameters:

Name	Type	Description	Default
s3Path	str	Tam S3 yolu (s3a://bucket/prefix/...)	required
basePath	str | None	Partition tabanlı tablolarda kök yolu. Belirtilmezse s3Path'den otomatik çıkarılmaz.	None
format	str	"parquet" (varsayılan) veya "csv"	'parquet'
columns	list[str] | None	Okunacak sütun listesi. None → tüm sütunlar	None

Returns:

Type	Description
object	pyspark.sql.DataFrame

loadMobilityData(province: str | None = None, columns: list[str] | None = None) -> object

MapinData standart S3 şemasından (echo_data_partitioned) mobil veri yükler.

S3 yolu ConfigManager üzerinden dinamik oluşturulur

s3a://{s3Bucket}/{s3RawPrefix}echo_data_partitioned/

Partition filter

province="Istanbul" → .../province=Istanbul/ province=None → tüm partition'lar (dikkatli kullan, büyük veri!)

Parameters:

Name	Type	Description	Default
province	str | None	İl adı (partition filter için). None → tüm iller	None
columns	list[str] | None	Okunacak sütun listesi. None → MOBILITY_DEFAULT_COLUMNS	None

Returns:

Type	Description
object	pyspark.sql.DataFrame — seçili sütunlarla filtrelenmiş mobil veri

stop() -> None

Spark oturumunu kapatır ve dahili referansı temizler.

---

Koordinat Tanımlama

Koordinat anlamlandırma motoru.

Bir enlem/boylam çiftini hiyerarşik kaynak sorgusuyla POI kimliğine dönüştürür: 1. master.poi (İç DB) — en yüksek güvenilirlik (0.98) 2. public.coordinate_cache — önceki Google sorguları (0.85) 3. Google Places API (opsiyonel, useGoogle=True) — canlı sorgu (0.72)

Google Places yalnızca açıkça useGoogle=True verildiğinde çağrılır. Başarılı Google sorguları otomatik olarak cache tablosuna kaydedilir.

Kullanım

cfg = ConfigManager() pg = PgClient(cfg)

Sadece iç DB + cache

identifier = CoordinateIdentifier(pgClient=pg) result = identifier.identify(40.9887, 29.0240)

Google fallback aktif

from mapindata.scraping import GooglePlacesClient google = GooglePlacesClient(cfg) identifier = CoordinateIdentifier(pgClient=pg, googleClient=google) result = identifier.identify(40.9887, 29.0240, useGoogle=True)

Çıktı formatı

{ "coordinate": {"lat": 40.9887, "lon": 29.0240}, "source": "internal_db" | "cache" | "google" | None, "poi_id": "MAPIN_12345" | "ChIJ..." | None, "name": "Mekan Adı" | None, "primary_category": "HORECA" | "RETAIL" | ... | None, "sub_category": "Bar" | "Tekel" | ... | None, "raw_type": "Modern Pub & Bistro" | "liquor_store" | None, "confidence_score": 0.98 | 0.85 | 0.72 | 0.0, "h3_index": "891f1d48b2fffff" | None, }

raw_type: Kategorinin geldiği kaynaktaki orijinal ham string. - internal_db → master.poi.category değeri ("Modern Pub & Bistro", "Kebap" vb.) - cache / google → Google Places primaryType değeri ("liquor_store", "cocktail_bar" vb.) - LLM pipeline'ında semantik zenginlik için korunur; Mapin dönüşümü bu alana dokunmaz.

__init__(pgClient: PgClient, googleClient: object = None)

Parameters:

Name	Type	Description	Default
pgClient	PgClient	Başlatılmış PgClient — İç DB ve cache erişimi için	required
googleClient	object	GooglePlacesClient (opsiyonel) — yalnızca useGoogle=True ile kullanılır	None

identify(lat: float, lon: float, radiusMeters: float = 20.0, useGoogle: bool = False) -> dict

Koordinatı anlamlandırır ve standart POI sözlüğü döndürür.

Kaynak önceliği

1. master.poi (İç DB) — onaylı, güvenilir kayıt
2. public.coordinate_cache — önceki Google sorgusu kaydı
3. Google Places API — yalnızca useGoogle=True ise çağrılır; bulunan sonuç cache tablosuna otomatik kaydedilir.

Parameters:

Name	Type	Description	Default
lat	float	Enlem (WGS-84)	required
lon	float	Boylam (WGS-84)	required
radiusMeters	float	Arama yarıçapı metre cinsinden (varsayılan 20m)	20.0
useGoogle	bool	True ise iç DB ve cache'te bulunamazsa Google'a sorulur. False (varsayılan) ise Google çağrısı hiç yapılmaz.	False

Returns:

Type	Description
dict	Standart POI sözlüğü (ayrıntı için sınıf docstring'ine bakın)

---

Mobilite Motorları

Mobil konum verisi üzerinden ayak izi metriklerini hesaplar.

Desteklenen filtreleme yöntemleri

• polygon : Polygon / MultiPolygon / GeoJSON dosyası
• haversine: Merkez nokta + yarıçap (metre)

Büyük veri modu (S3): - DuckDB: con + s3Path ile başlatılır (varsayılan motor, 70× daha hızlı polygon) - Spark : df ile başlatılır

Motor seçimi her metod çağrısında engine parametresiyle yapılır

engine="duckdb" (varsayılan) engine="spark"

Küçük veri / lokal mod: _countByPolygonLocal / _countByRadiusLocal (dahili kullanım)

__init__(df: object = None, con: object = None, s3Path: str | None = None, latCol: str = _DEFAULT_LAT_COL, lonCol: str = _DEFAULT_LON_COL, deviceCol: str = _DEFAULT_DEVICE_COL)

Parameters:

Name	Type	Description	Default
df	object	Spark DataFrame (Spark motoru için)	None
con	object	DuckDB bağlantısı — DuckDBClient.connect() (DuckDB motoru için)	None
s3Path	str | None	DuckDB'nin okuyacağı S3 glob yolu — DuckDBClient.s3Path(province)	None
latCol	str	Enlem sütunu adı	_DEFAULT_LAT_COL
lonCol	str	Boylam sütunu adı	_DEFAULT_LON_COL
deviceCol	str	Cihaz ID sütunu adı	_DEFAULT_DEVICE_COL

fetchDeviceRecords(deviceIds: list, engine: str = ENGINE_DUCKDB)

Belirtilen device ID'lerin tüm kayıtlarını döndürür.

DuckDB : pandas.DataFrame Spark : pyspark.sql.DataFrame ≤ 1 000 device: isin / IN (hızlı)

1 000 device: broadcast join (Spark) / geçici tablo (DuckDB)

Parameters:

Name	Type	Description	Default
deviceIds	list	Sorgulanacak device_aid listesi	required
engine	str	"duckdb" (varsayılan) veya "spark"	ENGINE_DUCKDB

getCountByPolygon(polygonCoords: list | str | dict, engine: str = ENGINE_DUCKDB) -> int

Polygon / MultiPolygon içindeki unique device sayısını döndürür.

Coğrafi girdi formatları

list : Doğrudan koordinat dizisi (Polygon veya MultiPolygon) str : GeoJSON dosya yolu (.json) dict : GeoJSON Feature / Geometry nesnesi

Parameters:

Name	Type	Description	Default
polygonCoords	list | str | dict	Polygon, MultiPolygon koordinatları veya GeoJSON yolu/nesnesi	required
engine	str	"duckdb" (varsayılan) veya "spark"	ENGINE_DUCKDB

Returns:

Type	Description
int	Unique device sayısı (int)

getCountByPolygonSpark(df, polygonCoords: list) -> int

Deprecated: getCountByPolygon(coords, engine='spark') kullanın.

getCountByRadius(centerLat: float, centerLon: float, radiusMeters: float, engine: str = ENGINE_DUCKDB) -> int

Haversine yarıçapı içindeki unique device sayısını döndürür.

Parameters:

Name	Type	Description	Default
centerLat	float	Merkez enlem	required
centerLon	float	Merkez boylam	required
radiusMeters	float	Yarıçap (metre)	required
engine	str	"duckdb" (varsayılan) veya "spark"	ENGINE_DUCKDB

Returns:

Type	Description
int	Unique device sayısı (int)

getCountByRadiusSpark(df, centerLat: float, centerLon: float, radiusMeters: float) -> int

Deprecated: getCountByRadius(lat, lon, r, engine='spark') kullanın.

getDeviceList(polygonCoords: list | str | dict, engine: str = ENGINE_DUCKDB)

Polygon / MultiPolygon içindeki unique device ID listesini döndürür.

DuckDB : list[str] Spark : pyspark.sql.DataFrame (device_aid sütunu)

Parameters:

Name	Type	Description	Default
polygonCoords	list | str | dict	Polygon, MultiPolygon koordinatları veya GeoJSON yolu/nesnesi	required
engine	str	"duckdb" (varsayılan) veya "spark"	ENGINE_DUCKDB

getDeviceListByPolygonSpark(df, polygonCoords: list)

Deprecated: getDeviceList(coords, engine='spark') kullanın.

getDeviceListByRadius(centerLat: float, centerLon: float, radiusMeters: float, engine: str = ENGINE_DUCKDB)

Haversine yarıçapı içindeki unique device ID listesini döndürür.

DuckDB : list[str] Spark : pyspark.sql.DataFrame (device_aid sütunu)

getDeviceListByRadiusSpark(df, centerLat: float, centerLon: float, radiusMeters: float)

Deprecated: getDeviceListByRadius(lat, lon, r, engine='spark') kullanın.

Cihaz sinyallerini 5 zaman dilimine göre analiz eder.

Kullanım::

segmenter = TimeSegmenter()
result = segmenter.segment(signals_df, period_days=30)
# result["time_segments"]["prime_time_19_23"] → 0.35

segment(signals: pd.DataFrame, period_days: int, timestampCol: str = 'timestamp') -> dict[str, Any]

Sinyal DataFrame'ini analiz eder.

Parameters:

Name	Type	Description	Default
signals	DataFrame	Ham sinyal DataFrame. timestampCol kolonu Unix epoch int (saniye) içermeli.	required
period_days	int	Kart periyodu gün sayısı (frequency_score payda). periodToRange'den gelen gün değeri beklenir.	required
timestampCol	str	Unix epoch timestamp kolonu adı (varsayılan "timestamp").	'timestamp'

Returns:

Type	Description
dict[str, Any]	time_segments ve activity_metrics içeren dict.
dict[str, Any]	DataFrame boşsa tüm segment değerleri 0.0, metrikler 0 döner.

Cihaz sinyallerinden ev/iş mahallesi ve hareketlilik yarıçapı tahmin eder.

S3 Parquet sinyallerindeki neighborhood kolonu (%98 dolu) kullanılır; PostGIS bağımlılığı yoktur.

Parameters:

Name	Type	Description	Default
pgClient	Any	Aktif PgClient örneği (ileriki genişleme için korunuyor).	required

Kullanım::

from mapindata.data import PgClient
from mapindata.core import ConfigManager
from mapindata.mobility import HomeDetector

pg = PgClient(ConfigManager())
detector = HomeDetector(pg)
result = detector.detect(signals_df)

detect(signals: pd.DataFrame, timestampCol: str = 'timestamp', neighborhoodCol: str = 'neighborhood', latCol: str = 'latitude', lonCol: str = 'longitude') -> dict[str, Any]

Sinyal DataFrame'ini analiz ederek lokasyon DNA'sını döndürür.

Parameters:

Name	Type	Description	Default
signals	DataFrame	Ham sinyal DataFrame. timestampCol Unix epoch (int64, saniye), neighborhoodCol mahalle adı string, latCol/lonCol float64.	required
timestampCol	str	Unix epoch kolon adı.	'timestamp'
neighborhoodCol	str	Mahalle adı kolon adı (S3 Parquet: "neighborhood").	'neighborhood'
latCol	str	Enlem kolon adı.	'latitude'
lonCol	str	Boylam kolon adı.	'longitude'

Returns:

Type	Description
dict[str, Any]	location_dna dict:: { "home_neighborhood": str | None, "work_neighborhood_inferred": str | None, "top_visited_neighborhoods": list[str], "mobility_radius_km": float, }

---

Analitik Motorlar

Mekan ziyaretçi akışı ve yoğunluk metriklerini hesaplar.

Kullanım::

flow = VisitorFlow()
result = flow.analyze(signals_df, period_days=90)

analyze(signals: pd.DataFrame, period_days: int, deviceCol: str = 'device_aid', timestampCol: str = 'timestamp') -> dict[str, Any]

Sinyal DataFrame'ini analiz eder.

Parameters:

Name	Type	Description	Default
signals	DataFrame	Ham sinyal DataFrame. deviceCol string cihaz ID, timestampCol Unix epoch int (saniye).	required
period_days	int	Kart periyodu gün sayısı (signal_density_index payda).	required
deviceCol	str	Cihaz kimliği kolon adı (varsayılan "device_aid").	'device_aid'
timestampCol	str	Unix epoch timestamp kolon adı (varsayılan "timestamp").	'timestamp'

Returns:

Type	Description
dict[str, Any]	visitor_stats ve density_analytics içeren dict.

Rakip mekan sayımı ve mahalle SES analizi.

Parameters:

Name	Type	Description	Default
pgClient	Any	Aktif PgClient örneği.	required

Kullanım::

from mapindata.analytics import CompetitorAnalysis
ca = CompetitorAnalysis(pg)
result = ca.analyze(lat=41.05, lon=29.01, category="Off-Trade")

analyze(lat: float, lon: float, category: str, radiusMeters: float = 500.0, neighborhoodName: Optional[str] = None, neighborhoodId: Optional[int] = None) -> dict[str, Any]

Rakip analizi yürütür.

Parameters:

Name	Type	Description	Default
lat	float	Mekan enlemi.	required
lon	float	Mekan boylamı.	required
category	str	Hedef mekanın master.poi.category değeri (rakip filtresi).	required
radiusMeters	float	Arama yarıçapı metre cinsinden (varsayılan 500).	500.0
neighborhoodName	Optional[str]	Mahalle adı (SES sorgusu için, opsiyonel).	None
neighborhoodId	Optional[int]	Mahalle ID'si (SES sorgusu için, opsiyonel; name'den öncelikli).	None

Returns:

Type	Description
dict[str, Any]	nearby_competitors, neighboring_attractions ve ses_score içeren dict.

---

KART Sistemi (Identity)

Kişi ve Mekan Kartlarını identity.cards tablosunda saklar.

Parameters:

Name	Type	Description	Default
pgClient	Any	Aktif PgClient örneği.	required

Kullanım::

store = CardStore(pg)
store.save(card_dict, ttlDays=30)
card = store.get("device_uuid", "30d")

get(id: str, period: str) -> Optional[dict]

Belirtilen id + period için aktif (süresi dolmamış) kartı döndürür.

Parameters:

Name	Type	Description	Default
id	str	Kart kimliği (device_aid veya poi mapin_id).	required
period	str	Periyot string'i, örn. "30d", "90d".	required

Returns:

Type	Description
Optional[dict]	Kart JSON dict veya süresi dolmuşsa / yoksa None.

getVisitors(placeId: str, period: str) -> list[str]

Belirli periyot için mekanı ziyaret eden benzersiz kişi ID listesini döndürür.

Parameters:

Name	Type	Description	Default
placeId	str	Mekan POI kimliği.	required
period	str	Periyot string'i.	required

Returns:

Type	Description
list[str]	person_id string listesi. Kayıt yoksa boş liste.

invalidate(id: str, period: str) -> None

Kartın expires_at'ini anında geçmişe ayarlayarak geçersiz kılar.

Parameters:

Name	Type	Description	Default
id	str	Kart kimliği.	required
period	str	Periyot string'i.	required

linkVisitor(placeId: str, personId: str, period: str, visitDate: datetime.date) -> None

Mekan ↔ Kişi ziyaret ilişkisini identity.card_links'e kaydeder.

Çakışmada (aynı (place, person, period, date) PK) sessizce geçer.

Parameters:

Name	Type	Description	Default
placeId	str	Mekan POI kimliği.	required
personId	str	Kişi device_aid.	required
period	str	Periyot string'i.	required
visitDate	date	Ziyaret tarihi (datetime.date).	required

save(card: dict, ttlDays: int = 30) -> None

Kartı identity.cards tablosuna yazar; varsa günceller.

Parameters:

Name	Type	Description	Default
card	dict	En üst düzeyde id, type, period anahtarları olan KART dict.	required
ttlDays	int	Kartın geçerli olacağı gün sayısı (varsayılan 30).	30

Raises:

Type	Description
ValueError	card dict'te zorunlu alanlar eksikse.

Ham cihaz sinyallerinden Kişi Kartı üretir ve saklar.

Bağımlılıklar

• footfallEngine: Sinyal verisi için FootfallEngine örneği.
• coordinateIdentifier: Koordinat → POI kategorisi için CoordinateIdentifier örneği.
• pgClient: Mahalle DB sorgularına erişim için PgClient örneği.
• cardStore: Kart saklama için CardStore örneği.

Kullanım::

builder = PersonCardBuilder(
    footfallEngine=engine,
    coordinateIdentifier=ci,
    pgClient=pg,
    cardStore=store,
)
card = builder.build(deviceId="uuid-123", periodDays=30)

build(deviceId: str, periodDays: int = 30, ttlDays: int = 30, forceRebuild: bool = False) -> dict[str, Any]

Kişi Kartı JSON'unu üretir.

Parameters:

Name	Type	Description	Default
deviceId	str	Cihaz kimliği (device_aid).	required
periodDays	int	Sinyal periyodu gün sayısı (varsayılan 30).	30
ttlDays	int	Kart geçerlilik süresi gün (varsayılan 30).	30
forceRebuild	bool	True ise önbellekteki kartı görmezden gelir.	False

Returns:

Type	Description
dict[str, Any]	Kişi Kartı dict.

POI verilerinden Mekan Kartı üretir ve saklar.

Bağımlılıklar

• footfallEngine: Ziyaretçi tespiti için FootfallEngine örneği.
• pgClient: POI bilgisi ve mahalle sorguları için PgClient örneği.
• cardStore: Kart saklama ve kişi kartı okuma için CardStore örneği.

Kullanım::

builder = PlaceCardBuilder(
    footfallEngine=engine,
    pgClient=pg,
    cardStore=store,
)
card = builder.build(poiId="TR_IST_12345", periodDays=90)

build(poiId: str, periodDays: int = 90, ttlDays: int = 30, radiusMeters: float = 200.0, forceRebuild: bool = False) -> dict[str, Any]

Mekan Kartı JSON'unu üretir.

Parameters:

Name	Type	Description	Default
poiId	str	POI kimliği (master.poi.mapin_id).	required
periodDays	int	Sinyal periyodu gün sayısı (varsayılan 90).	90
ttlDays	int	Kart geçerlilik süresi gün (varsayılan 30).	30
radiusMeters	float	Ziyaretçi tespiti için mekan yarıçapı metre (varsayılan 200).	200.0
forceRebuild	bool	True ise önbellekteki kartı görmezden gelir.	False

Returns:

Type	Description
dict[str, Any]	Mekan Kartı dict.

---

Scraping

Google Places API (New) — koordinat bazlı mekan sorgulama istemcisi.

API anahtarı GOOGLE_PLACES_API_KEY env değişkeninden alınır. ConfigManager üzerinden yönetilir; hiçbir değer doğrudan kodda sabitlenmez.

Kullanım

cfg = ConfigManager() client = GooglePlacesClient(cfg)

Tek koordinat sorgusu

result = client.getPlaceByCoordinate(40.9887, 29.0240) print(result["name"], result["primaryType"], result["placeId"])

DataFrame zenginleştirme

df_enriched = client.enrichDataFrame(df, latCol="lat", lonCol="lon")

__init__(config: ConfigManager, timeoutSec: int = 10)

Parameters:

Name	Type	Description	Default
config	ConfigManager	ConfigManager — GOOGLE_PLACES_API_KEY buradan okunur	required
timeoutSec	int	HTTP istek timeout süresi (saniye, varsayılan 10)	10

enrichDataFrame(df: pd.DataFrame, latCol: str = 'lat', lonCol: str = 'lon', radiusMeters: float = 10.0, languageCode: str = 'tr', rateLimitDelay: float = 0.05) -> pd.DataFrame

DataFrame'deki her satır için getPlaceByCoordinate çağırır ve sonuçları yeni kolonlar olarak ekleyip döndürür.

g_placeId, g_name, g_primaryType, g_types,

g_googleMapsUri, g_cid, g_address

Parameters:

Name	Type	Description	Default
df	DataFrame	Enlem/boylam kolonları içeren pandas DataFrame	required
latCol	str	Enlem kolon adı (varsayılan "lat")	'lat'
lonCol	str	Boylam kolon adı (varsayılan "lon")	'lon'
radiusMeters	float	Her koordinat için arama yarıçapı (metre)	10.0
languageCode	str	Sonuç dili	'tr'
rateLimitDelay	float	Satırlar arası bekleme süresi (saniye). Google Places API'de 60 istek/dakika limiti vardır; 0.05s ≈ 1200 istek/dakika — production için 0.1s önerilir.	0.05

Returns:

Type	Description
DataFrame	Orijinal DataFrame'in kopyası + g_ prefixli yeni kolonlar

getPlaceByCoordinate(lat: float, lon: float, radiusMeters: float = 10.0, maxResults: int = 1, languageCode: str = 'tr') -> dict | None

Verilen koordinata en yakın Google Places mekanını döndürür.

İstekte yalnızca maliyet-optimizasyonlu alan maskesi kullanılır (Nearby Search Pro SKU; Atmosphere/Enterprise alanları dahil değil).

Parameters:

Name	Type	Description	Default
lat	float	Enlem (WGS-84)	required
lon	float	Boylam (WGS-84)	required
radiusMeters	float	Arama yarıçapı (metre, varsayılan 10)	10.0
maxResults	int	Maksimum sonuç sayısı (1–20, varsayılan 1)	1
languageCode	str	Sonuç dili (varsayılan "tr")	'tr'

Returns:

Type	Description
dict | None	maxResults=1 ise en yakın mekan dict'i (veya None).
dict | None	maxResults>1 ise list[dict].
dict | None	Her dict: placeId, resourceName, name, language, primaryType, types, googleMapsUri, cid, address, lat, lon

Raises:

Type	Description
HTTPError	API HTTP hata döndürdüğünde
ValueError	API hata mesajı döndürdüğünde