Atoka API User Reference

Job Ads Search

This API allows you to search for job ads. Currently only a limited amount of ads are included, but we don't exclude to add more and more in the future. Data is provided by our partner Indeed; this APIs joins their data with the power of the atoka engine, allowing fine-grained searches.

Remember that you can start your search from the Company Search API as well, with the jobs parameter.

https://api.atoka.io/v2/jobs

All requests must be properly authenticated.

Response

By default this API endpoint returns the list of job ads matching the selected criteria.

Using these parameters, you'll be able to customize the output you'll get from your searches.

Parameters
  • token string required

    All requests must be properly authenticated; see the Authentication section for more info

  • fields array,
    default is items

    Get just the list of job ads matched, or the search facets (or both!).

    If you set this to value none, you'll get just the meta object, with count of job ads matching your search criteria.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • items
    • facets
    • none
  • facetFields array

    We want to keep our API as fast as possible, but facets are expensive to compute. To avoid slowing things down, you must explicitly state which facets you want when you request them. We want to make your life as simple as possible, though, that's why we support wildcards to be used in here; with them you will be able to have an initial look at the data, and to explicitly specify the facets you need once you start developing your application.

    This field is required when requesting the search facets through the fields parameter

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • * Enable all the facets of all the requested packages
    • base.* Enable all the facets of the package "base"
    • base.address.macroregion
    • base.address.municipality
    • base.address.province
    • base.address.region
    • base.company.ateco
    • base.company.legalForms
    • base.open
    • base.source
    • base.sponsored
    • base.types
curl -G "https://api.atoka.io/v2/jobs" -d "fields=items,facets" -d "facetFields=base.*"

Response modifications

When fields is items, the response will be:

{
"items": [
{
"id": "string", // Unique ID that you can use throughout the API endpoints to reference to a specific job ad
"subject": "string" // The subject of the job ad
},
...
],
"meta": { // Meta information on search results
"ordering": "string", // Requested sorting algorithm.
"count": int, // Total number of records matching search query.
"limit": int, // As per search parameters, maximum number of records fetched per request.
"offset": int, // As per search parameters, number of records skipped.
"info": [ // A list of information messages, if any.
"string",
...
]
}
}
curl -G "https://api.atoka.io/v2/jobs" -d "fields=items"

When fields is facets, the response will be:

{
"facets": {
},
"meta": { // Meta information on results
"count": int, // Total number of objects returned
"info": [ // A list of information messages, if any.
"string",
...
]
}
}
curl -G "https://api.atoka.io/v2/jobs" -d "fields=facets"

Data packages

This parameter is left for future, as currently only one package is available for job ads. In the future you will be able to fine tune the fields you want to be returned by the API, similarly to what is done in the other Atoka APIs.

If you have special needs and want to further customize the data returned, we can adapt the output to your specific needs: just get in touch with us at sales@atoka.io.

Parameters
  • packages array

    Fine tune the results to the level of detail your application actually requires.

    The extraction cost per single job ads will be multiplied to the number of results in your query (up to offset parameter value).

    To avoid using any package, don't pass this parameter and the results will contain just the Atoka Job Ads ID (and little more).

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • base
    • * (use all the data packages you have an active subscription for)
curl -G "https://api.atoka.io/v2/jobs" -d "packages=*"

Response modifications

When packages is *, the response will be:

{
"items": [
{
"id": "string", // Unique ID that you can use throughout the API endpoints to reference to a specific job ad
"subject": "string", // The subject of the job ad
},
...
],
"facets": {
},
"queryExplanation": [
{ // Submitted query explanation.
"engine": "string",
"text": "string",
"json": object
},
...
],
"meta": { // Meta information on search results
"ordering": "string", // Requested sorting algorithm.
"count": int, // Total number of records matching search query.
"limit": int, // As per search parameters, maximum number of records fetched per request.
"offset": int, // As per search parameters, number of records skipped.
"info": [ // A list of information messages, if any.
"string",
...
]
}
}
curl -G "https://api.atoka.io/v2/jobs" -d "packages=*"

Ordering & Pagination

To download long lists of results you can paginate returned items using these parameters.

You can also decide the order in which items are returned.

Parameters
  • limit integer,
    default is 10

    This is the number of individual objects that are returned in each page.

    Use a number between 0 and 50.

  • offset integer,
    default is 0

    This offsets the start of each page by the number specified.

    Use a number between 0 and 9950.

  • ordering string,
    default is "published"

    Selects the order in which results are returned.

    Choose only one among:

    • published
curl -G "https://api.atoka.io/v2/jobs" -d "limit=10" -d "offset=30" -d "ordering=amount"

General info

These filters act on the general information of the job ads, such as the publication date or the job type.

Parameters
  • countries array,
    default is it

    Find jobs based in the specified countries.

    For the moment the only countries covered are Italy (it) and U.K. (uk), but we will soon extend it with more countries.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • it
    • uk
    • * matches for any value
  • ids array

    Search via already known Atoka Job Ads ID.

    Accepts multiple values, separated with , (comma) char.

  • query string

    This parameters allows a fulltext search on the job ads subject and description.

  • types array base

    Filter based on the job type. A single job ad may propose multiple job types

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • permanent For IT: tempo indeterminato
    • fulltime For IT: tempo pieno
    • temporary For IT: tempo determinato
    • parttime For IT: lavoro part-time
    • contract For IT: lavoro a progetto
    • internship For IT: tirocinio
    • recruiter For IT: somministrazione
    • casual For IT: collaborazione
    • subcontract For IT: partita IVA
    • commission For IT: agente
    • * matches for any value
  • publishedMin integer base

    Match job ads older than the specified amount of days.

  • publishedMax integer base

    Match job ads older no more than the specified amount of days.

  • open boolean base

    Match open job ads only.

  • sponsored boolean base

    Match sponsored job ads only.

  • sources array base

    Match only job ads of the given source(s).

    Accepts multiple values, separated with , (comma) char.

curl -G "https://api.atoka.io/v2/jobs" -d "publishedMin=6" -d "publishedMax=24" -d "open=true" -d "sponsored=true"

Location

Use these filters to find job ads located in a specific municipality, province or region.

Parameters
  • macroregions array base

    Match job ads offered in the given macroregion(s)

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • nord-ovest
    • nord-est
    • sud
    • centro
    • isole
  • regions array base

    Match job ads offered in the given region(s).

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • provinces array base

    Match job ads offered in the given province(s).

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • municipalities array base

    Match job ads offered in the given municipalit(y|ies).

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

curl -G "https://api.atoka.io/v2/jobs"

Company info

You can filter job ads based on information about the company they refer to (when available). This list is currently limited, but can be easily extended based on your needs, so don't hesitate to contact us! And remember, you can always use the Company Search API for complex queries, using the jobs parameter to limit your search to those companies offering at least one job position.

Parameters
  • companies array base

    Search via already known Company ID.

    Accepts multiple values, separated with , (comma) char.

  • companyLegalForms array base

    Filter job ads where its company has the given legal form of business (country specific).

    You can use the Legal Forms service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • companyLegalFormsExclude array base

    Exclude job ads where its company has the given legal form of business (country specific).

    You can use the Legal Forms service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • companyAteco array base

    Match job ads where its company has an ATECO activity code starting with provided value (for example: 12.34 matches 12.34.56 and also 12.34.87.90).

    Mutually exclusive with atecoExclude parameter: they cannot be used together.

    You can use the ATECO service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • companyAtecoExclude array base

    Exclude job ads where its company has an ATECO activity code starting with provided value (for example: 47.11 will exclude 47.11.01 and also 47.11.55.07).

    Mutually exclusive with ateco parameter: they cannot be used together.

    Accepts multiple values, separated with , (comma) char.

curl -G "https://api.atoka.io/v2/jobs" -d "companyAteco=62.09.09"

Debug

Use these parameters when you need to understand how your request was evaluated by the API.

Parameters
  • explain boolean,
    default is false

    When using this parameter in your request you'll get and additional property in the results explanation, that contains all the filters actually used during the query.

    Mostly useful for debugging purposes.

curl -G "https://api.atoka.io/v2/jobs" -d "explain=true"

Response modifications

When explain is true, the response will be:

curl -G "https://api.atoka.io/v2/jobs" -d "explain=true"