Parâmetros da API Job Search: práticas recomendadas (v3)

Como configurar a API

Fatores que afetam os resultados da pesquisa

Juntos, "Vagas em destaque", "Ativar ampliação" e "Desativar correspondência de palavras-chave" têm um impacto significativo no número e na relevância das vagas retornadas ao candidato. A configuração mais apropriada desses três fatores depende das necessidades da sua empresa. O melhor método para determinar a configuração ideal é aplicar diferentes cenários de teste e avaliar os resultados durante uma fase de testes.

  1. Vagas em destaque: use "Vagas em destaque" para atribuir valores promocionais a vagas individuais, o que permite destacar as que são importantes para as necessidades do seu negócio. Consulte a documentação Vagas em destaque para ver melhores práticas e detalhes de implementação.

  2. disableKeywordMatch: este parâmetro permite que a API retorne correspondências de palavras-chave, além dos resultados relevantes determinados pelo algoritmo de ML. A configuração padrão é false. Se essa configuração for mantida, a API Job Search do CTS retornará vagas que não foram retornadas como relevantes pelo algoritmo de ML, mas que têm uma correspondência de palavra-chave no título ou na descrição da vaga com a string de consulta do candidato. Se o parâmetro for definido como true, a correspondência de palavra-chave será desativada e menos vagas (somente aquelas determinadas como relevantes pelo recurso de ML) serão retornadas.

  3. enableBroadening: este parâmetro permite expandir a consulta do candidato diminuindo as restrições determinadas sobre local e categorias de vaga. Ele é definido como false por padrão e ativado quando definido como true. Ele é usado para aumentar o número de resultados de pesquisa retornados.

Resultados da configuração de pesquisa

Para retornar apenas as vagas mais relevantes: defina disableKeywordMatch como true e enableBroadening como false. Isso melhora as métricas de desempenho da API relativas à relevância da pesquisa, porque somente as vagas relevantes são retornadas. No entanto, menos vagas são retornadas nos resultados da pesquisa em geral.

Para retornar um número maior de vagas, incluindo resultados relevantes e que correspondam à palavras-chave: defina disableKeywordMatch como false e enableBroadening como false. Os resultados com correspondência de palavra-chave serão listados após as vagas relevantes nos resultados, mas os resultados da expansão de consulta não serão retornados.

Para retornar um número maior de vagas, incluindo vagas relevantes e com expansão de consulta: defina disableKeywordMatch como true e enableBroadening como true. A consulta do candidato será expandida para incluir categorias de vagas relacionadas e locais próximos, listados após os resultados relevantes. As correspondências com base em palavras-chave não são retornadas.

Para retornar o maior número possível de vagas: defina disableKeywordMatch como false e enableBroadening como true. A API Job Search retorna as vagas mais relevantes na parte superior dos resultados da pesquisa, seguidas por vagas com correspondência de palavra-chave e com expansão de consulta (por local, categoria de vaga etc). Isso aumenta o número total de vagas retornadas.

diasableKeywordMatch enableBroadening Resultado
- - Retorna um número maior de vagas, incluindo resultados relevantes e com correspondência de palavra-chave (mas pressupõe que "Vagas em destaque" esteja definido como "false").
+ + Retorna um número maior de vagas, incluindo resultados relevantes e com expansão de consulta (mas pressupõe que "Vagas em destaque" esteja definido como "false").
- + Retorna o maior número de vagas (mas pressupõe que "Vagas em destaque" esteja definido como "false").
+ - Retorna somente as vagas mais relevantes (mas pressupõe que "Vagas em destaque" esteja definido como "false").

Request.page_size

Para ter um melhor desempenho e evitar latência, configure a página de resultados para exibir 20 ou menos vagas por vez.

customAttributes

customAttributes oferece a flexibilidade de atribuir outros valores às vagas de acordo com as necessidades da sua empresa (por exemplo, pontuações de GPA) e usar esses valores para filtrar os resultados.

Campo "Local"

Veja uma visão geral detalhada do campo "Local" na página Campo "Local". Fornecer o endereço da vaga em vez de coordenadas GPS no campo de endereço ajuda a API a melhorar a detecção da localização e a relevância da pesquisa.

locationFilter

Use o regionCode se uma única empresa tiver várias vagas em diferentes regiões geográficas. A atribuição de um regionCode a cada listagem garante que uma consulta de pesquisa retorne vagas apenas no local desejado do candidato em vez dos resultados globais da empresa. Por exemplo, uma pesquisa pela palavra-chave de local "Cambridge" sem um regionCode retorna resultados de Cambridge, Reino Unido e Cambridge, MA, EUA. Isso diminui a relevância da pesquisa.

Region_code e Language_code

Defina request.filters.location_filters.region_code para corresponder à região geográfica que o usuário está pesquisando (como o Reino Unido). Defina request.filters.language_code como o código de idioma apropriado para a região (en_GB neste caso) para que a API possa usar a lógica de pesquisa localizada (por exemplo, "motorista de caminhão" em en_GB em vez de "motorista de caminhão" nos Estados Unidos).

radiusinMiles

Esse parâmetro define um raio (em milhas) em torno do local indicado pelo candidato. A API retorna resultados dentro dessa faixa geográfica. A maneira como essa distância é aplicada à geografia dos resultados da pesquisa depende do tipo de informações de local inseridas. Se o candidato inserir um endereço, a distância radiusInMiles será definida a partir de um único ponto. Se ele inserir uma cidade, a API aplicará uma caixa delimitadora nos limites da cidade e calculará a distância a partir das bordas da caixa. Se o usuário inserir apenas um estado ou país, radiusInMiles será ignorado.

Procure definir o menor raio de milhagem possível. Caso contrário, serão retornados resultados que podem estar fora do local desejado do candidato, o que diminui a relevância. Por exemplo, uma pesquisa por vagas na cidade de Nova York com radiusInMiles definido como 100 milhas retornará resultados em Nova York e Nova Jersey. Mantenha o raio o menor possível para aumentar a relevância dos resultados.

postingExpireTime

Esse parâmetro define o período em que a publicação da vaga permanecerá ativa antes de ser removida dos resultados da pesquisa. O padrão é 30 dias após a hora de criação da vaga no fuso horário UTC.

Job_employment_type

Esse não é um campo obrigatório, mas usar Job_employment_type aumenta a relevância dos resultados da pesquisa de vagas.

Como configurar a API: classificação personalizada

Com as Vagas em destaque, é possível influenciar os resultados da pesquisa e destacar as vagas com base em uma única variável (promotionValue). Consulte a documentação sobre vagas em destaque para mais detalhes. A Classificação personalizada oferece a capacidade de influenciar os resultados com base em várias variáveis, oferecendo mais controle sobre as classificações independentemente da relevância. Esse recurso é útil em aplicativos que requerem o equilíbrio entre relevância e interesses econômicos, como um sistema de assinantes de custo por clique (CPC) com vários níveis. Além da pontuação de relevância, a ordem das vagas é baseada em duas variáveis: rankingExpression e importanceLevel.

  • rankingExpression: essa variável controla como as vagas são classificadas com base nas pontuações de relevância atuais, conforme determinado pelo algoritmo da API. "rankingExpression" precisa ser definido como "filterable" para que a API indexe o parâmetro.

  • importanceLevel: este parâmetro define o nível de importância da posição de classificação de uma vaga quando ela é retornada nas pesquisas. Existem seis níveis diferentes: não especificado, NONE, LOW, MID, HIGH e EXTREME. Se você definir o valor como EXTREME, todos os outros fatores relevantes gerados pela API serão ignorados. Portanto, use esse valor com moderação. As vagas definidas como EXTREME são retornadas na parte superior da consulta do candidato em vez das vagas mais relevantes.

  • Vagas em destaque x Classificação personalizada: Vagas em destaque é mais útil para promover uma única categoria de vagas (por exemplo, vagas em uma determinada empresa) acima da classificação de relevância. Se você precisar classificar as vagas de acordo com as variáveis de CPC (custo por clique) de vários níveis e com a classificação de relevância, a Classificação personalizada será a melhor opção.

A pesquisa por deslocamento diário ajuda os candidatos a procurar vagas com base no tempo de deslocamento. Para ativá-la, inclua um objeto CommuteFilter extra no campo JobQuery.commuteFilter. Esse objeto permite que o candidato à vaga selecione commuteMethod, travelDuration e startCoordinates. O candidato também pode selecionar opções como roadTraffic (TRAFFIC_FREE ou BUSY_HOUR) e departureTime ao calcular o tempo de deslocamento diário. Para mais detalhes, consulte a página de implementação e o guia de instruções da pesquisa por deslocamento diário.

Gerenciamento de dados e tratamento de erros

Integridade dos dados

  1. Upload de vagas: problemas de dados podem impedir que as vagas sejam enviadas para a API. Veja a página Códigos de resposta HTTP para mais informações. Alguns exemplos comuns:

    • Os locais da vaga estão incorretos, portanto, a solicitação não pode ser resolvida.
    • Os campos "Empresa" ou "Vaga" não existem, o que retorna uma solicitação inválida.

    Há três opções principais para solucionar problemas de upload de vagas:

  2. Indexação de vagas: a API Job Search foi projetada para indexar todas as vagas que você faz upload em um determinado período. No entanto, é possível que você tenha restrições de cota. Verifique seu sistema quanto a restrições nas solicitações de indexação antes de enviar vagas para o CTS.

Mecanismos de tratamento de erros

O tratamento de erros é crucial para evitar um ataque de DDoS auto-infligido que resulte no bloqueio de candidatos. Os serviços de API fornecidos pela Internet também podem ter falha de conexão intermitente, interrupção prolongada, manutenção de serviço repentina e outros eventos que exigem que um aplicativo cliente tente executar novamente a solicitação de API. Essa nova tentativa precisa ser projetada com um comportamento amigável para a rede, por exemplo, com a retirada exponencial.

Deduplicação

As vagas duplicadas afetam negativamente a experiência de pesquisa de um candidato. A API Job Search inclui dois recursos para minimizar duplicatas:

  1. Criar vagas: se você tentar criar mais de duas vagas com os critérios a seguir, o registro será rejeitado e você receberá um erro 4xx:

    • mesmo companyName, E
    • mesmo job_req_id, E
    • mesmo local/languageCode

  2. Pesquisar vagas: a API Job Search do CTS exibe vagas que são relevantes para a consulta de pesquisa do candidato. Um recurso integrado do algoritmo de relevância garante que todas as vagas retornadas sejam diversificadas, evitando que vagas quase idênticas apareçam lado a lado nos resultados da pesquisa.