Vacature-facetten ophalen

Het facets-endpoint levert geaggregeerde data over beschikbare filteropties voor vacatures. Dit is ideaal voor het bouwen van dynamische zoekinterfaces met facetnavigatie, waarbij gebruikers zien welke filters beschikbaar zijn en hoeveel resultaten elk filter zou opleveren.

Overzicht

Dit endpoint retourneert aantallen voor alle beschikbare filteropties, rekening houdend met eventueel actieve filters. Het is efficiënter dan ?include=facets gebruiken op het hoofdlijstendpoint wanneer je alleen facetdata nodig hebt zonder de daadwerkelijke vacaturelijsten.

Eenvoudig voorbeeld

Haal alle beschikbare facetten op zonder filters:

``bash cURL


curl -X GET https://app\.recruitsome\.com/api/v1/vacancies/facets \
  -H "Authorization: Bearer YOUR_API_KEY"

javascript JavaScript
const response = await fetch('https://app\.recruitsome\.com/api/v1/vacancies/facets', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const facets = await response.json();

python Python
import requests

response = requests.get(
    'https://app\.recruitsome\.com/api/v1/vacancies/facets',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

facets = response.json()


Voorbeeld van een response

json
{
  "data": {
    "locations": [
      {
        "id": 1,
        "name": "Amsterdam",
        "city": "Amsterdam",
        "country_code": "NL",
        "country_name": "Netherlands",
        "count": 45,
        "selected": false
      },
      {
        "id": 2,
        "name": "Rotterdam",
        "city": "Rotterdam",
        "country_code": "NL",
        "country_name": "Netherlands",
        "count": 23,
        "selected": false
      },
      {
        "id": 3,
        "name": "Utrecht",
        "city": "Utrecht",
        "country_code": "NL",
        "country_name": "Netherlands",
        "count": 18,
        "selected": false
      }
    ],
    "company_locations": [
      {
        "id": 10,
        "name": "Shell Pernis Refinery",
        "city": "Rotterdam",
        "country_code": "NL",
        "country_name": "Netherlands",
        "count": 12,
        "selected": false
      },
      {
        "id": 11,
        "name": "ASML Veldhoven HQ",
        "city": "Veldhoven",
        "country_code": "NL",
        "country_name": "Netherlands",
        "count": 8,
        "selected": false
      }
    ],
    "departments": [
      {
        "id": 5,
        "name": "Engineering",
        "count": 32,
        "selected": false
      },
      {
        "id": 6,
        "name": "Sales",
        "count": 21,
        "selected": false
      },
      {
        "id": 7,
        "name": "Marketing",
        "count": 15,
        "selected": false
      }
    ],
    "experience_levels": [
      {
        "id": 2,
        "name": "Junior",
        "count": 20,
        "selected": false
      },
      {
        "id": 3,
        "name": "Medior",
        "count": 35,
        "selected": false
      },
      {
        "id": 4,
        "name": "Senior",
        "count": 28,
        "selected": false
      }
    ],
    "job_types": [
      {
        "id": 1,
        "name": "Full-time",
        "count": 68,
        "selected": false
      },
      {
        "id": 2,
        "name": "Part-time",
        "count": 12,
        "selected": false
      },
      {
        "id": 3,
        "name": "Contract",
        "count": 8,
        "selected": false
      }
    ],
    "education_levels": [
      {
        "id": 8,
        "name": "Bachelor",
        "count": 45,
        "selected": false
      },
      {
        "id": 9,
        "name": "Master",
        "count": 28,
        "selected": false
      }
    ],
    "tags": [
      {
        "id": 1,
        "name": "Engineering",
        "count": 42,
        "selected": false,
        "sub_tags": [
          {
            "id": 5,
            "name": "Software Engineer",
            "count": 25,
            "selected": false
          },
          {
            "id": 6,
            "name": "DevOps Engineer",
            "count": 12,
            "selected": false
          }
        ]
      },
      {
        "id": 2,
        "name": "Sales",
        "count": 28,
        "selected": false,
        "sub_tags": [
          {
            "id": 10,
            "name": "Account Executive",
            "count": 15,
            "selected": false
          }
        ]
      }
    ],
    "languages": [
      {
        "code": "en",
        "name": "English",
        "count": 52,
        "selected": false
      },
      {
        "code": "nl",
        "name": "Nederlands",
        "count": 34,
        "selected": false
      }
    ]
  },
  "meta": {
    "generated_at": "2024-01-20T10:30:00Z",
    "filters_applied": []
  }
}
Voorbeeld met filters

Haal facetten op met actieve filters om te zien hoe selecties andere opties beïnvloeden:

bash cURL
curl -X GET "https://app\.recruitsome\.com/api/v1/vacancies/facets?\
location_id[]=1&\
language=en" \
  -H "Authorization: Bearer YOUR_API_KEY"

javascript JavaScript
const params = new URLSearchParams({
  'location_id[]': 1,
  'language': 'en'
});

const response = await fetch(

https://app\.recruitsome\.com/api/v1/vacancies/facets?${params},


  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const facets = await response.json();

python Python
import requests

params = {
    'location_id[]': 1,
    'language': 'en'
}

response = requests.get(
    'https://app\.recruitsome\.com/api/v1/vacancies/facets',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params=params
)

facets = response.json()


Wanneer filters worden toegepast:
Het selected-veld toont true voor actieve filters

Aantallen in andere facetcategorieën worden bijgewerkt om alleen de gefilterde resultaten weer te geven
De filters_applied-array in meta toont welke filters actief zijn


Queryparameters

Parameter Type Verplicht Beschrijving
language string Nee Filter op taalcode (bijv. 'en', 'nl', 'de')
location_id[] array Nee Filter op locatie-ID's (ondersteunt meerdere)
company_location_id[] array Nee Filter op bedrijfslocatie-ID's (werklocatie, voor uitzendbureaus)
department_id[] array Nee Filter op afdelings-ID's (ondersteunt meerdere)
search string Nee Zoek in titel en samenvatting
experience_levels[] array Nee Filter op ervaringsniveau-ID's
education_levels[] array Nee Filter op opleidingsniveau-ID's
job_types[] array Nee Filter op dienstverband-ID's
tags[] array Nee Filter op tag-ID's (hoofdtags worden doorvertaald naar subtags)
<div class="not-prose rounded-lg border border-gray-200 bg-gray-50 p-4 dark:border-gray-700 dark:bg-gray-800"><p class="mt-1 text-sm text-gray-700 dark:text-gray-300">De company_location_id-parameter ondersteunt arraynotatie op zowel dit endpoint als het hoofdendpoint voor vacatures. location_id en department_id ondersteunen arraynotatie alleen op dit facets-endpoint.</p></div>


Facetaantallen begrijpen

Zonder filters
Wanneer er geen filters zijn toegepast, toont elk facet het totale aantal actieve vacatures met dat kenmerk:
Locatie "Amsterdam" aantal: 45 = Totaal aantal actieve vacatures in Amsterdam
Afdeling "Engineering" aantal: 32 = Totaal aantal actieve vacatures bij Engineering

Met actieve filters
Wanneer filters zijn toegepast, tonen de aantallen hoeveel resultaten overeenkomen met zowel het facet ALS de huidige filters:
Bij filteren op Amsterdam: Afdeling "Engineering" aantal: 12 = Vacatures in Amsterdam EN Engineering
De locatie Amsterdam zelf toont "selected": true

Responsstructuur


Facet-objectstructuur

Elk facettype bevat een array van opties met:

Veld Type Beschrijving
id integer Unieke identifier voor de optie
name string Leesbare naam (vertaald)
count integer Aantal vacatures met dit kenmerk
selected boolean Of dit filter momenteel actief is
Locatiefacetten

Locatiefacetten bevatten aanvullende geografische informatie:

Veld Type Beschrijving
id integer Unieke locatie-identifier
name string Locatienaam
city string\ null Plaatsnaam (uit het locality-veld)
country_code string\ null ISO 3166-1 alpha-2 landcode
country_name string\ null Volledige landnaam in de huidige taalinstelling
count integer Aantal vacatures op deze locatie
selected boolean Of dit filter momenteel actief is
<div class="not-prose rounded-lg border border-gray-200 bg-gray-50 p-4 dark:border-gray-700 dark:bg-gray-800"><p class="mt-1 text-sm text-gray-700 dark:text-gray-300">Voor remote functies of locaties zonder specifieke stad kan het city-veld null zijn.</p></div>


Bedrijfslocatiefacetten

Bedrijfslocatiefacetten vertegenwoordigen de daadwerkelijke werklocaties (locaties van het opdrachtgevende bedrijf) voor uitzend- en detacheringstenants. Deze array is leeg voor niet-uitzendtenants of wanneer er geen vacatures aan een bedrijfslocatie zijn gekoppeld.

Veld Type Beschrijving
id integer Unieke bedrijfslocatie-identifier
name string Naam van de bedrijfslocatie
city string\ null Plaatsnaam (uit het locality-veld)
country_code string\ null ISO 3166-1 alpha-2 landcode
country_name string\ null Volledige landnaam in de huidige taalinstelling
count integer Aantal vacatures op deze werklocatie
selected boolean Of dit filter momenteel actief is
<div class="not-prose rounded-lg border border-gray-200 bg-gray-50 p-4 dark:border-gray-700 dark:bg-gray-800"><p class="mt-1 text-sm text-gray-700 dark:text-gray-300">Het company_locations-facet bevat niet de bedrijfsnaam om onbedoelde onthulling van klantrelaties te voorkomen. Gebruik de include_company_name-parameter op de vacaturelijst-/detail-endpoints als je bedrijfsnamen nodig hebt.</p></div>


Tagfacetten (hiërarchisch)

Tagfacetten gebruiken een hiërarchische structuur met hoofdcategorieën die geneste subtags bevatten:

Veld Type Beschrijving
id integer Unieke tag-identifier
name string Tagnaam (vertaald)
count integer Totaal aantal vacatures in deze categorie (inclusief subtags)
selected boolean Of dit filter momenteel actief is
sub_tags array Array van subcategorietags
Elk sub_tags-item bevat: id, name, count en selected.


<div class="not-prose rounded-lg border border-gray-200 bg-gray-50 p-4 dark:border-gray-700 dark:bg-gray-800"><p class="mt-1 text-sm text-gray-700 dark:text-gray-300">Bij het filteren op een hoofdtag (bijv. "Engineering") worden alle vacatures die getagd zijn met een van de bijbehorende subtags automatisch in de resultaten opgenomen.</p></div>

Taalfacetten

Taalfacetten hebben een iets andere structuur:

Veld Type Beschrijving
code string ISO 639-1 taalcode
name string Taalnaam
count integer Aantal vacatures in deze taal
selected boolean Of dit filter momenteel actief is
Toepassingen

Dynamische filters bouwen

Gebruik facetdata om filterinterfaces te maken die beschikbare opties en aantallen tonen:

javascript
// Bouw een locatiefilter-dropdown met uitgebreide geografische info
const locationFilter = facets.data.locations.map(location => ({
  value: location.id,

Parameter	Type	Verplicht	Beschrijving
language	string	Nee	Filter op taalcode (bijv. 'en', 'nl', 'de')
location_id[]	array	Nee	Filter op locatie-ID's (ondersteunt meerdere)
company_location_id[]	array	Nee	Filter op bedrijfslocatie-ID's (werklocatie, voor uitzendbureaus)
department_id[]	array	Nee	Filter op afdelings-ID's (ondersteunt meerdere)
search	string	Nee	Zoek in titel en samenvatting
experience_levels[]	array	Nee	Filter op ervaringsniveau-ID's
education_levels[]	array	Nee	Filter op opleidingsniveau-ID's
job_types[]	array	Nee	Filter op dienstverband-ID's
tags[]	array	Nee	Filter op tag-ID's (hoofdtags worden doorvertaald naar subtags)

Veld	Type	Beschrijving
id	integer	Unieke identifier voor de optie
name	string	Leesbare naam (vertaald)
count	integer	Aantal vacatures met dit kenmerk
selected	boolean	Of dit filter momenteel actief is

Veld	Type	Beschrijving
id	integer	Unieke locatie-identifier
name	string	Locatienaam
city	string\	null	Plaatsnaam (uit het locality-veld)
country_code	string\	null	ISO 3166-1 alpha-2 landcode
country_name	string\	null	Volledige landnaam in de huidige taalinstelling
count	integer	Aantal vacatures op deze locatie
selected	boolean	Of dit filter momenteel actief is

Veld	Type	Beschrijving
id	integer	Unieke bedrijfslocatie-identifier
name	string	Naam van de bedrijfslocatie
city	string\	null	Plaatsnaam (uit het locality-veld)
country_code	string\	null	ISO 3166-1 alpha-2 landcode
country_name	string\	null	Volledige landnaam in de huidige taalinstelling
count	integer	Aantal vacatures op deze werklocatie
selected	boolean	Of dit filter momenteel actief is

Veld	Type	Beschrijving
id	integer	Unieke tag-identifier
name	string	Tagnaam (vertaald)
count	integer	Totaal aantal vacatures in deze categorie (inclusief subtags)
selected	boolean	Of dit filter momenteel actief is
sub_tags	array	Array van subcategorietags

Veld	Type	Beschrijving
code	string	ISO 639-1 taalcode
name	string	Taalnaam
count	integer	Aantal vacatures in deze taal
selected	boolean	Of dit filter momenteel actief is

label: ${location.name} (${location.count}),


  description: location.city && location.country_name

? ${location.city}, ${location.country_name}


    : location.country_name || '',
  disabled: location.count === 0,
  checked: location.selected
}));

// Voorbeelduitvoer:
// {
//   value: 1,
//   label: "Amsterdam Office (45)",
//   description: "Amsterdam, Netherlands",
//   disabled: false,
//   checked: false
// }

Slimme filterupdates

Wanneer een gebruiker een filter selecteert, haal dan bijgewerkte facetten op om te tonen hoe dit andere opties beïnvloedt:

javascript
async function onFilterChange(filters) {
  // Haal nieuwe facetten op met huidige filters
  const facets = await fetchFacets(filters);
  
  // Werk de UI bij om nieuwe aantallen te tonen
  updateFilterCounts(facets);
  
  // Schakel opties zonder resultaten uit
  disableEmptyFilters(facets);
}

Filteropties vooraf laden

Laad facetten bij het laden van de pagina om direct beschikbare filters te tonen:

javascript
// Bij het laden van de pagina
const [vacancies, facets] = await Promise.all([
  fetchVacancies({ page: 1 }),
  fetchFacets({})
]);

// Initialiseer filters met facetdata
initializeFilters(facets);

Prestatieoverwegingen

Caching: Facetdata verandert minder vaak dan vacatureoverzichten, waardoor het ideaal is voor caching
Parallel laden: Haal facetten parallel op met de initiële vacaturedata voor snellere laadtijden
Debouncing: Gebruik debouncing bij het implementeren van live filterupdates om overmatige API-aanroepen te voorkomen
Voorwaardelijke updates: Haal facetten alleen opnieuw op wanneer filters daadwerkelijk wijzigen

Foutmeldingen

Ongeldige filterparameter
json
{
  "message": "The given data was invalid.",
  "errors": {
    "location_id.0": ["The location_id.0 must be a valid location."]
  }
}

API-toegang uitgeschakeld
json
{
  "message": "API access is not enabled for this tenant."
}

Best practices

Cache facetresultaten: Implementeer client-side caching met een passende TTL
Lege statussen afhandelen: Ontwerp de UI zodat facetten met nul resultaten netjes worden weergegeven
Progressive enhancement: Laad de initiële pagina met basisfilters en verrijk deze met facetdata
Gebundelde updates: Wanneer meerdere filters wijzigen, verwerk ze samen in één enkel verzoek
Laadstatussen: Toon laadindicatoren tijdens het ophalen van bijgewerkte facetten

Vacaturefacetten ophalen

Vacature-facetten ophalen

Overzicht

Eenvoudig voorbeeld

Voorbeeld van een response

Voorbeeld met filters

Queryparameters

Facetaantallen begrijpen

Zonder filters

Met actieve filters

`Responsstructuur`

Facet-objectstructuur

Locatiefacetten

Bedrijfslocatiefacetten

Tagfacetten (hiërarchisch)

Taalfacetten

Toepassingen

Dynamische filters bouwen

Slimme filterupdates

Filteropties vooraf laden

Prestatieoverwegingen

Foutmeldingen

Ongeldige filterparameter

API-toegang uitgeschakeld

Best practices

Lees ook