Atoka API User Reference

Contract Search

This API allows you to search for contracts with the Government. Currently, only contracts for Italy are included, which are those sent to the Italian National Anti-Corruption Authority. This powerful API will allow you to search exactly what you are looking for, to understand how companies participate and integrate with the Government, and how public money is spent.

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

All requests must be properly authenticated.

Response

By default this API endpoint returns the list of contracts 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 contracts matched, or the search facets (or both!).

    If you set this to value none, you'll get just the meta object, with count of contracts 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.amount
    • base.amountPaid
    • base.commissioningBody.legalForms
    • base.commissioningBody.registeredAddress.macroregion
    • base.commissioningBody.registeredAddress.municipality
    • base.commissioningBody.registeredAddress.postcode
    • base.commissioningBody.registeredAddress.province
    • base.commissioningBody.registeredAddress.region
    • base.contractorSelection
    • base.endDate
    • base.participantGroups.participants.ateco
    • base.participantGroups.participants.legalForms
    • base.participantGroups.participants.registeredAddress.macroregion
    • base.participantGroups.participants.registeredAddress.municipality
    • base.participantGroups.participants.registeredAddress.postcode
    • base.participantGroups.participants.registeredAddress.province
    • base.participantGroups.participants.registeredAddress.region
    • base.startDate
curl -G "https://api.atoka.io/v2/contracts" -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 contract
"subject": "string" // The subject of the contract it self
},
...
],
"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/contracts" -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/contracts" -d "fields=facets"

Data packages

This parameter is left for future, as currently only one package is available for Contracts. 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 contract 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 Contract 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/contracts" -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 contract
"subject": "string", // The subject of the contract it self
},
...
],
"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/contracts" -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 "startDateDesc"

    Selects the order in which results are returned.

    Choose only one among:

    • startDate
    • startDateDesc
    • endDate
    • endDateDesc
    • amount
    • amountDesc
curl -G "https://api.atoka.io/v2/contracts" -d "limit=10" -d "offset=30" -d "ordering=amount"

General info

These filters act on the general information of the contract, such as the contract amount, the starting / ending dates, and so on.

Parameters
  • ids array

    Search via already known Atoka Contract ID.

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

  • subject string

    This parameters allows a fulltext search on the contracts subject.

  • cig array base

    The CIG ("Codice Identificativo Gara") is the unique ID for Italian contracts; not all the contracts are required to have one, therefore this field may be empty.

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

  • startDateFrom string base

    This filter can be used to retrieve all the contracts which starting date is after the one provided.

  • startDateTo string base

    This filter can be used to retrieve all the contracts which starting date is up to the one provided.

  • endDateFrom string base

    This filter can be used to retrieve all the contracts which ending date is after the one provided.

  • endDateTo string base

    This filter can be used to retrieve all the contracts which ending date is up to the one provided.

  • amountMin number base

    Retrieve only those contract with an amount greater or equal to the one given.

  • amountMax number base

    Retrieve only those contracts with an amount lower or equal to the one given.

  • amountPaid array base

    It could happen that a contract is not fully covered (yet); this may happen for several reasons: the service for which the contract was stipulated has not started yet, it may be it's still active and was covered only partially, it could even be that more expenses arised and the amount paid actually exceeded the amount granted. This filter allows you to retrieve contracts based on this aspect. Please notice that the amount paid is not always available, and therefore this field may be incalculable.

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

    Possible values are:

    • more
    • equal
    • less
    • incalculable
    • * matches for any value
  • contractorSelection array base

    How was the contractor selected? Was it a public auction? Was it a direct assignment? For values containing , (comma) char, please wrap them with double apices "

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

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

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

Commissioning Body info

These filters allow you to filter by the Commissioning Body (the client) of the contract, which will be Government Organisations. You can either filter for a specific GO or by a geographical area you may be interested in.

Parameters
  • commissioningBodies array base

    Search via already known Atoka Government Organisation ID.

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

  • commissioningBodyMacroregions array base

    Match contracts commissioned by a subject with registered address in one of the provided macro-regions.

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

  • commissioningBodyRegions array base

    Match contracts commissioned by a subject with registered address in one of the provided regions.

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

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

  • commissioningBodyProvinces array base

    Match contracts commissioned by a subject with registered address in one of the provided provinces.

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

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

  • commissioningBodyMunicipalities array base

    Match contracts commissioned by a subject with registered address in one of the provided municipalities.

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

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

  • commissioningBodyPostcodes array base

    Match contracts commissioned by a subject with registered address in one of the provided postcodes.

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

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

Participants info

Obviously you can filter contracts based on who applied to it, either winning or not. Companies may apply to contracts in groups, in case of a company applying individually, the API will return a group composed by a single participant.

All these fields operate together, which means that you can combine them to produce complex queries referring to the contracts participants. For example, by specifying participantsAwarded=true and participantsMunicipalities=Trento,Bolzano the API will return all the contracts where (one of) the awarded participants are located either in Trento or in Bolzano.

In other words, all these filters will return those contracts where at least one of the participants matches all the given filters, where multiple values of the same filter are evaluated with OR.

The list of participants in the Contract Search API is limited to 20; if you need to retrieve all of them, please use the Contract Details API.

Parameters
  • participants array base

    Search via already known Company ID.

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

  • participantsGroups array base

    Search via already known Group ID.

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

    THIS FEATURE IS NOT IMPLEMENTED, YET. If you need it, just get in touch with us at sales@atoka.io

  • participantsAwarded boolean base

    Filter contracts where the participant(s) either won or lost the contract.

  • participantsMacroregions array base

    Filter contracts where the participant(s) has its registered address in this macro-region.

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

  • participantsRegions array base

    Filter contracts where the participant(s) has its registered address in this region. You can use the AdminDiv service to get possible values for this parameter.

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

  • participantsProvinces array base

    Filter contracts where the participant(s) has its registered address in this province. You can use the AdminDiv service to get possible values for this parameter.

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

  • participantsMunicipalities array base

    Filter contracts where the participant(s) has its registered address in this municipality. You can use the AdminDiv service to get possible values for this parameter.

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

  • participantsPostcodes array base

    Filter contracts where the participant(s) has its registered address in this postcode.

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

  • participantsLegalForms array base

    Filter contracts where the participant(s) 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.

  • participantsLegalFormsExclude array base

    Exclude contracts where the participant(s) 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.

  • participantsAteco array base

    Match contracts where the participant(s) 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.

  • participantsAtecoExclude array base

    Exclude contracts where the participant(s) 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/contracts" -d "participantsAteco=62.09.09"

Debug

Use these parameters when you need to undestand 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/contracts" -d "explain=true"

Response modifications

When explain is true, the response will be:

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

Contract Details

Show full details of a contract.

By default we show all information available using all the data packages you subscribed to. Use the package parameter to fine tune the output format.

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.

https://api.atoka.io/v2/contracts/{id}

Replace {id} with the Atoka Contract ID you want details for (as returned by the [Contract Search](#contracts)..

All requests must be properly authenticated.

Data Packages

This parameter is left for future, as currently only one package is available for Contracts. 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.

Remember: your subscription gives you access to different levels of detail in data returned!

Parameters
  • packages array,
    default is *

    By using this parameter you can fine tune the results to the level of detail your application actually requires.

    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/contracts/{id}" -d "packages=*"

Response modifications

When packages is *, the response will be:

{
"item": {
"id": "string", // Unique ID that you can use throughout the API endpoints to reference to a specific contract
"subject": "string", // The subject of the contract it self
},
"queryExplanation": [
{ // Submitted query explanation.
"engine": "string",
"text": "string",
"json": object
},
...
]
}
curl -G "https://api.atoka.io/v2/contracts/{id}" -d "packages=*"

Debug

Use these parameters when you need to undestand 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/contracts/{id}" -d "explain=true"

Response modifications

When explain is true, the response will be:

curl -G "https://api.atoka.io/v2/contracts/{id}" -d "explain=true"