API Documentation

Overview

This document provides guidelines and examples for API-accessible Service offering Analytical Tools.

You can use the GraphQL tool to manually issue GraphQL queries. If you navigate in a web browser to GraphQL, you should see an interface that lets you enter queries.

Try it

Authentication

Our API requests require authenication via an API key.

API key is issued after registration confirmation. You can find it in the API section on the Account page.

Here is an example of the request with the authentication header:

POST /ua/prozorro/graphql HTTP/1.0
Authorization: Bearer 8d490d5334159f9811d3ce760971b16d1dcef663
Content-Length: 138
Content-Type: application/json
Host: ocdsanalytics.com

{
  "query": "{ Predictions{ Unit(page: {limit: 1} filters:{eq: {field:\"title\" value: \"fuel\"}}){ values{ entity{ id  } probability }}}}"
}



200 OK
Access-Control-Allow-Headers: Content-Type
Access-Control-Allow-Methods: GET,POST,OPTIONS
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Tue, 23 Apr 2019 08:55:49 GMT
Server: gunicorn/19.9.0
Vary: Accept-Encoding

{
  "data": {
    "Predictions": {
      "Unit": {
        "values": [
          {
            "entity": {
              "id": "H87"
            },
            "probability": 0.50202125
          }
        ]
      }
    }
  }
}

If you are using our GraphQL interface, insert your API token into HTTP HEADERS section:

{
"AUTHORIZATION": "Bearer 8d490d5334159f9811d3ce760971b16d1dcef663"
}

Query

You can create complex queries, and then change the data output into whatever structure required using a variety of options .

Dataset

When receiving data collections, it is possible to limit the volume of this collections or predictions.

parameter description
filters:[{filter: {field: '', value: ''}] filter results by specific fields
page: {limit: '', offset: ''} paging

Filters

By applying a filter, you are able to limit the data in a view without altering the design of the underlying object.

There are several types of filters:

  • eq (equal)
{eq: {field: "item.classification.id", value: "35120000-1"}
  • gte (greater or equal)
{gte: {field: "probability", value: "0.5"}

Paging

You can limit Values when receiving data collections or predictios, without applying limit for Aggregations

  • limit: 4 means, ‘return a maximum of 4 records’
  • offset: 3 means, ‘skip the first 3 records’
page: {limit: 4, offset: 3}

Predictions

This subsystem is designed to provide predictions based on machine learning modules. Predictions is a simple Django app, which is used as plugin with analytics system.

Item Unit

Based on the inputs, we can get the most probable unit of measure. You are able to get Item Unit predictions with the following call:

    {
      Predictions {
        Unit(
          page: {limit: 4},
          filters:[
            {eq: {field: "tender.title", value: "Системи та пристрої нагляду та охорони (Двоканальний автомобільний відеореєстратор)"}},
            {eq: {field: "tender.description", value: "Системи та пристрої нагляду та охорони (Двоканальний автомобільний відеореєстратор)"}},
            {eq: {field: "item.description", value: "Двоканальний автомобільний відеореєстратор"}},
            {eq: {field: "item.classification.id", value: "35120000-1"}},
            {gte: {field: "probability", value: "0.02"}}
          ]){
          values{
            entity{
              id
              name
              symbol
            }
            probability
          }
        }
      }
    }

Results:

    {
      "data": {
        "Predictions": {
          "Unit": {
            "values": [
              {
                "entity": {
                  "id": "H87",
                  "name": "штуки",
                  "symbol": "шт."
                },
                "probability": 0.8850628733634949
              },
              {
                "entity": {
                  "id": "E50",
                  "name": "Одиниця",
                  "symbol": "од."
                },
                "probability": 0.05140087381005287
              },
              {
                "entity": {
                  "id": "KT",
                  "name": "комплект",
                  "symbol": "комп."
                },
                "probability": 0.04352602735161781
              }
            ]
          }
        }
      }
    }

Item Classification

Based on the inputs, we can get the most probable item classification. To get Item Classification predictions use the following call:

    {
      Predictions {
        Classification(
          page: {limit: 3},
          filters:[
            {eq: {field: "tender.title", value: "Плитка керамічна"}},
            {eq: {field: "tender.description", value: "плитка керамічна"}},
            {eq: {field: "item.description", value: "Плитка керамічна Gress Атем Veneto, для підлоги, розмір – 400*400, колір – бежева, поверхня глазурована, матова"}},
            {eq: {field: "item.unit.id", value: "MTK"}},
            {gte: {field: "probability", value: "0.0002"}}
          ]){
          values{
            entity{
              id
              description
              scheme
            }
            probability
          }
        }
      }
    }

Results:

    {
      "data": {
        "Predictions": {
          "Classification": {
            "values": [
              {
                "entity": {
                  "id": "44110000-4",
                  "description": "Конструкційні матеріали",
                  "scheme": "ДК021"
                },
                "probability": 0.4496721625328064
              },
              {
                "entity": {
                  "id": "44111000-1",
                  "description": "Будівельні матеріали",
                  "scheme": "ДК021"
                },
                "probability": 0.15752540528774261
              },
              {
                "entity": {
                  "id": "44111700-8",
                  "description": "Кахель",
                  "scheme": "ДК021"
                },
                "probability": 0.09735838323831558
              }
            ]
          }
        }
      }
    }