IDs de referência de entidade

A SharpAPI emite identificadores inteiros estáveis (numerical_id) em cada entidade de referência, além de objetos de referência aninhados autodescritivos em cada linha de odds e leg de oportunidade. Esta página documenta o que esses IDs garantem, como usá-los e como eles se relacionam com os IDs de string existentes.

O que há de novo

Cada endpoint de referência (/sports, /leagues, /sportsbooks, /markets, /teams) agora retorna um inteiro numerical_id ao lado do id slug existente. /teams retorna adicionalmente um campo abbreviation quando disponível.

Cada linha de odds (e cada leg de uma oportunidade EV / arbitragem / middle) agora carrega seis objetos de referência aninhados opcionais que agrupam o id, o rótulo de exibição e o numerical_id da entidade diretamente com a linha — sem necessidade de segunda consulta a /sports ou /teams:

{
  "home": {
    "id": "new_york_yankees",
    "numerical_id": 20,
    "name": "New York Yankees",
    "abbreviation": "NYY",
    "logo": "https://cdn.opticodds.com/team-logos/baseball/36.png",
    "city": "New York",
    "mascot": "Yankees",
    "conference": "AL",
    "division": "East Division"
  },
  "away": {
    "id": "boston_red_sox",
    "numerical_id":  5,
    "name": "Boston Red Sox",
    "abbreviation": "BOS",
    "logo": "https://cdn.opticodds.com/team-logos/baseball/14.png",
    "city": "Boston",
    "mascot": "Red Sox",
    "conference": "AL",
    "division": "East Division"
  },
  "sport_ref":      { "id": "baseball",         "numerical_id":  3, "name": "Baseball" },
  "league_ref":     { "id": "mlb",              "numerical_id": 354, "label": "MLB" },
  "market_ref":     { "id": "moneyline",        "numerical_id": 878, "label": "Moneyline" },
  "sportsbook_ref": { "id": "pinnacle",         "numerical_id":  28, "label": "Pinnacle" }
}

Semântica do numerical_id

Cada numerical_id é alocado a partir de um registro congelado por domínio em api-adapters/sharp_atlas/. O contrato é:

Quando os campos estão ausentes

Os objetos de referência aninhados são emitidos somente quando a entidade subjacente foi mapeada no atlas. Para entidades não mapeadas — tipicamente ligas de cauda longa, mercados exóticos ou casas de apostas recém-adicionadas antes da atribuição de catálogo — o bloco *_ref correspondente é omitido (ou tem numerical_id: null) e o campo de string existente na linha é o único ID disponível.

Na prática:

• Principais esportes, ligas e casas são totalmente mapeados — espere que todos os blocos *_ref estejam presentes.
• Mercados de prop de jogadores e mercados de escanteios/cartões/períodos no futebol têm o catálogo mais amplo; alguns tipos de prop de nicho ainda estão sendo atribuídos.
• O abbreviation de times é preenchido onde amplamente conhecido (ligas principais dos EUA, EPL, códigos curtos ATP/WTA). Para times menores ou internacionais, pode estar ausente.

Os consumidores devem tratar cada bloco aninhado como opcional. Clientes genéricos devem recorrer ao campo de string plano (sport, league, sportsbook, home_team, away_team, market_type) quando o *_ref correspondente não estiver presente.

Uso recomendado

Indexação e joins

Use numerical_id como chave primária ao armazenar odds/oportunidades em seu próprio banco de dados. Chaves inteiras são menores, mais baratas de indexar e estáveis em relação a renomeações de slug ou ajustes de rótulo de exibição.

Mapeamento entre feeds

Se você ingere dados de múltiplos provedores, numerical_id fornece uma verificação de igualdade rápida dentro das linhas da SharpAPI. Para mapeamento entre fornecedores, o slug id ainda é a chave de join mais portátil — slugs são legíveis por humanos e tendem a se sobrepor entre fornecedores mais do que IDs inteiros.

Exibição na interface

Use name (esportes, times) ou label (ligas, mercados, casas de apostas) para exibição; o abbreviation em home/away é adequado para células compactas.

Streaming

Os mesmos objetos aninhados aparecem nos frames SSE de /api/v1/stream/odds e nos payloads de odds do WebSocket v1 / v1.5 — nenhum stream separado é necessário.

Referência de campos

Endpoints de referência

Cada endpoint de referência adiciona numerical_id ao seu esquema de objeto existente. /teams adicionalmente inclui abbreviation.

Blocos de referência aninhados em odds e legs de oportunidade

Todos os campos internos são opcionais dentro de um bloco. Um bloco pode estar presente com numerical_id como null se o slug foi mapeado mas a atribuição do inteiro está pendente; tanto numerical_id quanto o bloco inteiro também podem estar ausentes para entidades não mapeadas.

Campos de metadados de times

Os blocos home / away expõem cinco campos de metadados opcionais adicionais além de id / numerical_id / name / abbreviation. Eles são provenientes do atlas da SharpAPI e preenchidos para a grande maioria dos times (≈93% em logo, com cobertura comparável nos demais):

Competidores de esportes individuais (tenistas, lutadores de MMA, golfistas, pilotos) geralmente não têm nenhum desses campos preenchidos — eles não são “times” no sentido convencional e herdam apenas id / numerical_id / name.

Migração

Não há nada a migrar. Continue usando os campos de string planos se eles atenderem às suas necessidades. Adote os blocos *_ref e o numerical_id seletivamente quando:

• você precisar de uma chave inteira estável para armazenamento,
• quiser rótulos prontos para exibição sem uma segunda chamada de API,
• ou estiver construindo uma camada de normalização entre feeds.

Os campos planos e os blocos aninhados descrevem a mesma linha — eles não se contradirão.

Relacionados

• Sports, Leagues, Sportsbooks, Markets, Teams — endpoints de referência com o novo campo numerical_id
• Odds Snapshot, Oportunidades +EV, Arbitragem, Middles — endpoints com blocos de referência aninhados
• Correspondência de Eventos — como a SharpAPI une o mesmo evento entre casas de apostas