Insights

Leia a força de trabalho de pilotos como um mercado e mostre a um piloto onde ele está entre os colegas.

Os Insights têm duas leituras. Um parceiro com insights.read lê o Workforce: como os pilotos do MyPilotIndex se apresentam como mercado, em agregados. Um app de piloto com um grant que tem insights.position lê onde um piloto está em relação à coorte dele.

​

Leia o Workforce

curl "https://{api-host}/v1/partner/insights/workforce/overview?country=BR" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "schema_version": 1,
  "screen": "overview",
  "as_of": "2026-11-05",
  "generated_at": "2026-11-06T04:50:00Z",
  "cohort": { "status": "ok", "denominator": "cohort" },
  "privacy": { "cohort_floor": 20, "cell_floor": 5 },
  "sections": {
    "composition": {
      "status": "ok",
      "buckets": [{ "key": "major", "share_pct": 18, "suppressed": false }],
      "unpublished_pct": 2
    }
  }
}

São seis telas: overview, geography, qualifications, aircraft, score e intent. Cada uma aceita os mesmos filtros da tela de um membro, no máximo três por vez. A referência da API lista esses filtros. Um filtro desconhecido ou repetido, ou um valor fora do vocabulário, responde 400 invalid_request, e um nome fora das seis telas responde 404 not_found.

​

Como os números são protegidos

O servidor aplica os pisos, então o seu código nunca precisa fazer isso:

• Uma coorte abaixo do piso responde status: "insufficient" e nenhuma seção.
• Uma célula abaixo do próprio piso é suprimida, e a fatia que ela tinha aparece em unpublished_pct.
• Um filtro que deixaria poucos pilotos é removido, e a resposta informa isso em filters.broadened.

Nenhuma resposta traz uma contagem de pilotos. O tamanho de uma coorte é uma faixa, nunca um número. Uma publicação que nunca rodou responde só schema_version, screen, generated_at e cohort, com o status not_ready.

​

Mostre a um piloto a posição dele

curl https://{api-host}/v1/partner/grants/{grant_id}/workforce-position \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "schema_version": 1,
  "as_of": "2026-11-05",
  "generated_at": "2026-11-06T09:12:00Z",
  "privacy": { "cohort_floor": 20, "cell_floor": 5 },
  "cohort": { "status": "ok", "level": 2, "n_band": "250_499" },
  "metrics": {
    "total_hours": { "status": "ok", "percentile": 62, "cohort_median": 1180 },
    "score": { "status": "ok", "percentile": 71, "cohort_median": 431.5 },
    "type_rating_count": { "status": "missing" }
  }
}

As seis métricas são total_hours, pic_hours, score, type_rating_count, years_experience e international_hours. Cada uma tem um status ok, missing ou insufficient, e percentile e cohort_median só aparecem com ok.

cohort.level diz qual degrau da coorte respondeu, de 1, o mais específico, a 4, todos. A resposta não nomeia o piloto em lugar nenhum.