HTTP API

API methods

POST /jobs/features

Submit a feature calculation job.

Example request:

POST /jobs/features HTTP/1.1
Authorization: test5ab853b308th539test
Content-Type: application/json

{
    "points": [
        {
            "id": 1,
            "geopos": {
                "type": "Point",
                "coordinates": [30.33, 59.86]
            }
        }
    ],
    "features": {
        "apartments_r500": {
            "type": "circle",
            "dataset": "ru-pub-households/apartments",
            "limit": 500,
            "field": "price",
            "agg": "mean"
        }
    }
}

Example response:

HTTP/1.1 200 OK
Authorization: test5ab853b308th539test
Content-Type: application/json

{
    "job_id": "6665eb015d8001bf2e92",
    "total": 1
}

Request headers

Authorization

Authorization token.

GET /jobs/{job_id}

Get the job status.

Example request:

GET /jobs/6665eb015d8001bf2e92 HTTP/1.1
Authorization: test5ab853b308th539test

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "job_id": "6665eb015d8001bf2e92",
    "total": 1,
    "progress": 1,
    "failed": 0,
    "status": "completed"
}

Path parameters

job_id

ID of the submitted job.

Request headers

Authorization

Authorization token.

GET /jobs/{job_id}/result

Fetch the completed job result.

Example request:

GET /jobs/6665eb015d8001bf2e92/result HTTP/1.1
Authorization: test5ab853b308th539test

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": [
        {
            "id": 1,
            "apartments_r500": 252500.2
        }
    ],
    "total": 1,
    "progress": 1,
    "failed": 0,
    "status": "completed"
}

Path parameters

job_id

ID of the submitted job.

Request headers

Authorization

Authorization token.

DELETE /jobs/{job_id}

Abort a running job.

Aborting is not immediate: points that have already started are completed, while the remaining points are not calculated. When the job finishes, a partial result becomes available and only successfully calculated features are deducted from the balance.

Example request:

DELETE /jobs/6665eb015d8001bf2e92 HTTP/1.1
Authorization: test5ab853b308th539test

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "Accepted"
}

Path parameters

job_id

ID of the submitted job.

Request headers

Authorization

Authorization token.

GET /balance

Get the current user's resource balance.

Example request:

GET /balance HTTP/1.1
Authorization: test5ab853b308th539test

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "balance": {
        "faas_features": 100
    }
}

Request headers

Authorization

Authorization token.

Example

An example using the Python requests library:

import requests

FAAS_URL = 'https://faas.example.com'
FAAS_TOKEN = 'test5ab853b308th539test'

config = {
    'points': [
        {
            'id': 1,
            'geopos': {
                'type': 'Point',
                'coordinates': [30.33, 59.86]
            }
        },
    ],
    'features': {
        'apartments_r500': {
            'type': 'circle',
            'dataset': 'ru-pub-households/apartments',
            'limit': 500,
            'field': 'price',
            'agg': 'mean',
        },
    },
}

# Submit a job.
response = requests.post(
    f'{FAAS_URL}/jobs/features',
    headers={'Authorization': FAAS_TOKEN},
    json=config,
)
response.raise_for_status()
job_id = response.json()['job_id']

# Check the progress.
response = requests.get(
    f'{FAAS_URL}/jobs/{job_id}',
    headers={'Authorization': FAAS_TOKEN},
)
response.raise_for_status()
data = response.json()
print(
    f"{data['progress'] / data['total'] * 100}% done",
    f"{data['progress']} points done",
    f"{data['total']} total points",
    sep='\n'
)

# Fetch the completed job result.
response = requests.get(
    f'{FAAS_URL}/jobs/{job_id}/result',
    headers={'Authorization': FAAS_TOKEN},
)
response.raise_for_status()
result = response.json()['result']

# Use the result as a dataframe.
import pandas as pd

df = pd.DataFrame(result)