Skip to content

API Usage

The API Usage endpoint can be used to view the status of your API subscription.

GET /usage

📄❓ See Code Samples (page bottom) for an example request.

Retrieves the status of an API subscription, identified via the API key header (x-api-key) used to authenticate the request.

Response

Subscription

"subscription": {
    "last_renewed": "2024-02-06T13:46:13.110Z",
    "request_count": 17,
    "quota_period": "month",
    "quota": null,
    "quota_used": 0,
    "requests_remaining": null,
    "credit_limit": 2500,
    "credits_used": 180,
    "credits_remaining": 2320,
    "renews_at": "2024-03-06T13:46:13.110Z"
},

The subscription field contains general information about your API subscription:

  • Last Renewed: When the subscription was last renewed. This marks the start of your current quota period.
  • Request Count: The number of requests made since the last renewal.
  • Quota Period: A text label identifying how long each quota period lasts before renewal.
  • Quota: The number of requests that can be made per quota period.
  • Requests Remaining: The remaining number of requests that can be made before renewal.
  • Credit Limit: The number of credits that can be spent per quota period.
  • Credits Used: The number of credits that have been spent this quota period.
  • Credits Remaining: The number of credits that can still be spent before renewal.
  • Renews At: The date and time that the subscription will renew (resetting all quotas and credit balances).

Endpoints

"endpoints": [
    {
        "name": "EPCs",
        "path": "/epcs",
        "method": "GET",
        "description": "Retrieves EPCs for a given property",
        "affects_usage_plan_quota": true,
        "can_make_request": true,
        "credit_cost": 10,
        "credits_used": 150,
        "request_count": 15,
        "requests_remaining": null
    },
    ...
]

The endpoints field contains information about each endpoint that your subscription provides access to:

  • Name: The name of the endpoint.
  • Path: The path of the endpoint.
  • Method: The request method accepted by the endpoint.
  • Description: A text description of the endpoint.
  • Affects Usage Plan Quota: true if requests to the endpoint affect your overall usage for your subscription.
  • Can Make Request: true if you can make a request to the endpoint. (i.e. you have enough credits and quota)
  • Credit Cost: The number of credits that must be spent to make a request to the endpoint.
  • Credits Used: The number of credits that have been spent to use the endpoint this quota period.
  • Request Count: The number of requests that have been made to the endpoint this quota period.
  • Requests Remaining: The number of requests that can still be made to this end point this quota period (null if the endpoint does not have its own request quota).

Code Samples

Request

curl \
  -X GET \
  --header "x-api-key: <API KEY>" \
  https://api.propeco.io/usage

const results = await fetch(`https://api.propeco.io/usage`, {
  headers: {
    "x-api-key": API_KEY
  },
});
const data = await results.json();

Response

{
    "subscription": {
        "last_renewed": "2024-02-06T13:46:13.110Z",
        "request_count": 17,
        "quota_period": "month",
        "quota": null,
        "quota_used": 0,
        "requests_remaining": null,
        "credit_limit": 2500,
        "credits_used": 180,
        "credits_remaining": 2320,
        "renews_at": "2024-03-06T13:46:13.110Z"
    },
    "endpoints": [
        {
            "name": "EPCs",
            "path": "/epcs",
            "method": "GET",
            "description": "Retrieves EPCs for a given property",
            "affects_usage_plan_quota": true,
            "can_make_request": true,
            "credit_cost": 10,
            "credits_used": 150,
            "request_count": 15,
            "requests_remaining": null
        },
        {
            "name": "Properties",
            "path": "/properties/{uprn}",
            "method": "GET",
            "description": "Retrieves a property by UPRN",
            "affects_usage_plan_quota": true,
            "can_make_request": true,
            "credit_cost": 10,
            "credits_used": 0,
            "request_count": 0,
            "requests_remaining": null
        },
        {
            "name": "Location",
            "path": "/location",
            "method": "GET",
            "description": "Retrieves information about a given location in the UK",
            "affects_usage_plan_quota": true,
            "can_make_request": true,
            "credit_cost": 10,
            "credits_used": 0,
            "request_count": 0,
            "requests_remaining": null
        },
        {,
            "name": "Flood Risk",
            "path": "/flood-risk",
            "method": "GET",
            "description": "Retrieves information about the flood risk for a given property or location",
            "affects_usage_plan_quota": true,
            "can_make_request": true,
            "credit_cost": 10,
            "credits_used": 0,
            "request_count": 0,
            "requests_remaining": null
        },
        {,
            "name": "PropEco Energy Model",
            "path": "/energy-model",
            "method": "POST",
            "description": "Runs the PropEco Energy model",
            "affects_usage_plan_quota": true,
            "can_make_request": true,
            "credit_cost": 15,
            "credits_used": 30,
            "request_count": 2,
            "requests_remaining": null
        }
    ]
}