Normaliza los datos de la API de cuotas de Pinnacle sin perder su significado

Dos nombres de equipo idénticos y dos precios decimales no bastan para establecer una comparación. Los registros deben referirse al mismo evento, periodo de liquidación, regla de mercado, línea y selección. Trata la normalización como la preservación de esos significados, no solo como renombrar propiedades JSON.

El esquema de abajo es un diseño de aplicación propuesto. No describe un formato universal de feed.

Separa la identidad de la observación

Mantén una tabla canónica de eventos y una tabla aparte de correspondencia de feeds. Un ID canónico de evento debería permanecer estable cuando el feed cambia su ID o se corrige una hora de inicio. Conserva el ID original de la fuente junto a cada observación para poder auditar una unión más tarde.

Para un candidato a emparejamiento, compara deporte, competición, participantes, inicio programado y orientación local/visitante. Usa alias para generar candidatos y luego comprueba los conflictos. Enfrentamientos repetidos, partidos reprogramados, parejas de dobles, equipos reserva y sedes neutrales pueden derrotar al emparejamiento simple por nombre. Una puntuación de confianza puede enviar un candidato a revisión; no debería convertir silenciosamente la incertidumbre en identidad.

Los feeds derivados de Pinnacle muestran por qué importa el ID de la fuente. Un partido en vivo puede llegar como un enfrentamiento padre más enfrentamientos hijos reemitidos que comparten los mismos nombres de equipo, y el mismo mercado puede aparecer bajo dos ID a la vez, uno actual y uno de cierre, con precios distintos. Indexa las observaciones por el ID de evento del feed, nunca por los nombres de los equipos.

Mantén visibles las correspondencias no resueltas. Excluirlas de una comparación informando del recuento de exclusiones es preferible a mostrar una diferencia de precio precisa para eventos mal emparejados.

Construye la clave de mercado antes que la columna de precio

Elemento de la clave	Significado de ejemplo	Por qué no se puede descartar
Evento	ID canónico del partido	Los mismos equipos pueden enfrentarse más de una vez
Periodo	Partido completo, primera mitad, primer set	Los periodos son contratos distintos
Familia de mercado	Moneyline, total, hándicap	Los precios se refieren a conjuntos de resultados distintos
Regla de liquidación	Solo tiempo reglamentario, prórroga incluida	Etiquetas parecidas pueden liquidarse de forma distinta
Línea	Total 2.5, hándicap local -0.5	Líneas distintas no son precios intercambiables
Selección	Local, visitante, empate, más, menos, participante	Invertir la orientación crea diferencias falsas
Fuente	Feed y casa de apuestas subyacente	Un agregador y su fuente son identidades distintas

No infieras reglas de prórroga a partir del nombre de un deporte ni asignes un valor predeterminado no documentado. Una regla de liquidación desconocida debería bloquear una comparación que dependa de ella. Distingue mercados no disponibles, suspendidos, cerrados y abiertos; un valor ausente no es una cuota decimal de cero.

Un registro mínimo de observación

Estos son datos sintéticos ilustrativos, no una respuesta real de un feed ni una observación medida:

Los ejemplos de integración usan endpoints ficticios. Configura la URL base de la API y las credenciales de tu proveedor, y verifica su esquema actual antes de hacer una solicitud real.

{
  "schemaVersion": 1,
  "canonicalEventId": "example-event-001",
  "feedId": "example-feed",
  "sourceEventId": "example-source-event",
  "bookmakerId": "example-bookmaker",
  "period": "full_game",
  "market": "total",
  "settlementRule": "regulation_only",
  "line": "2.5",
  "selection": "over",
  "decimalOdds": "1.95",
  "status": "open",
  "sourceUpdatedAt": null,
  "receivedAt": "2026-09-26T10:00:00Z",
  "sourceSequence": null,
  "mappingVersion": "example-v1"
}

Las cadenas decimales hacen explícitas las decisiones de precisión. Analízalas con una representación numérica que entienda decimales cuando importe la identidad exacta de la línea. Normaliza 2.50 y 2.5 a la misma línea canónica conservando el valor bruto original en un almacenamiento de procedencia permitido. Rechaza precios malformados, números no finitos y cuotas decimales iguales o inferiores a uno.

El conversor de cuotas puede demostrar formatos de visualización; no resuelve la identidad del mercado. Conserva la representación de la fuente si el redondeo importara para análisis posteriores.

Dale un trabajo a cada marca de tiempo

sourceUpdatedAt debería significar exactamente lo que la fuente dice que significa. receivedAt registra cuándo tu recolector recibió la observación. El inicio programado de un evento no es ninguna de las dos. Representa las marcas de tiempo con zona horaria, como valores RFC 3339 en UTC; un formato de cadena estandarizado no establece la exactitud del reloj. RFC 3339.

Si no hay disponible una hora de actualización de la fuente, conserva el nulo. No lo rellenes con la hora de recepción para luego llamar latencia del feed a su diferencia. Cuando tengas una marca de tiempo de la fuente, registra su resolución y si se aplica a una selección individual, a una casa de apuestas o a un snapshot completo.

Haz la ingesta idempotente

Define una clave de deduplicación a partir de la fuente, el evento, el mercado, la selección y la secuencia documentada o la identidad de la observación. Si un feed no tiene una secuencia duradera, los hashes de contenido pueden suprimir repeticiones idénticas, pero no pueden demostrar que recibiste cada cambio intermedio.

Mantén una vista de estado actual separada del historial de observaciones. Un upsert de estado actual responde qué se vio por última vez; una tabla de observaciones de solo anexado responde qué vio el recolector a lo largo del tiempo. Versiona el mapeador para que una definición de mercado corregida pueda recalcularse sin reescribir el significado de los registros antiguos.

Antes de mostrar una diferencia, exige claves de mercado compatibles, precios válidos, estado conocido, antigüedad de observación aceptable y una correspondencia revisada. Continúa con la evaluación de datos históricos o la metodología de benchmark según el producto que estés construyendo.