Guavy API

Guavy API Documentation

Sector sentiment

get
/api/v3/index/sentiment/historical/{index_id}/{days}

This endpoint provides comprehensive daily sentiment analysis for any Guavy Guavy Index sector over a specified time period. The sentiment data aggregates news mentions across all cryptocurrencies within the selected index.

Sentiment analysis tracks positive, negative, and neutral mentions in cryptocurrency news coverage, enabling users to analyze market perception trends, identify sentiment shifts that may precede price movements, and correlate news sentiment with index performance.

Use the /index/list-all endpoint to retrieve available index IDs and their corresponding cryptocurrency collections before making sentiment requests.

Path Parameters
index_id
integer
required
The id of the index to fetch the sentiment for. Can be found in the /index/list-all route.
days
integer
required
The number of days to fetch the sentiment for. e.g. 7 returns the last week of data.

Example request with authentication

The example below demonstrates how to make an authenticated API request using cURL. All Guavy API endpoints require authentication via a Bearer token, which should be included in the Authorization header. This token identifies your account and determines your access level to various endpoints.

To use this example:

  1. Replace YOUR-GUAVY-ACCESS-TOKEN with your personal API key from the Guavy dashboard
  2. The URL includes the specific endpoint path shown in the documentation
  3. All requests use HTTPS for secure data transmission
curl --request GET \

--url 'https://api.guavy.com/api/v3/index/sentiment/historical/{index_id}/{days}' \

--header 'Authorization: Bearer YOUR-GUAVY-ACCESS-TOKEN' \
--header 'Content-Type: application/json'

This request format works across all modern HTTP clients, including Python requests, JavaScript fetch, and other programming language libraries.

API Playground

Test this API route directly in your browser using our interactive Swagger documentation. Simply authenticate with your API key, input parameters, and execute requests to see real-time responses and understand how each endpoint behaves.

HTTP server response

The Guavy API uses standard HTTP response codes and JSON formatting for all responses. This consistent structure allows for predictable parsing and error handling in your applications.

Response Structure

All responses from the API are delivered as JSON objects with the following characteristics:

  • HTTP status codes indicate the result category (2xx for success, 4xx for client errors, 5xx for server errors)
  • Content is always delivered with the application/json MIME type
  • Successful responses wrap data in a Success object
  • Error responses include descriptive messages to help troubleshoot issues

A successful response will look like this:

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

{
    "Success": {
        // Response payload containing requested data
    }
}

For large responses, consider implementing pagination using the limit and skip parameters where available to improve performance.

API response format

The Guavy API generally follows REST conventions, with some deviations.

  • All responses are wrapped in a top-level object.
  • Responses return either `Success` or `Error`.
  • Errors include a message field with details about the error.
  • All responses use the generic JSON content type.
  • Array responses are wrapped in an additional array layer.

An example of a successful response from this API endpoint is shown below:

{
    "Success": [
      {
        "id" : integer
        "name" : string
        "positive" : integer
        "negative" : integer
        "neutral" : integer
        "timestamp" : number
        "date" : string
      }
    ]
}

Response data types

The table below details all data fields returned by this endpoint, including their types and descriptions. Understanding these fields is essential for properly integrating this API into your application and extracting meaningful data from responses.

id
integer
Unique identifier for the cryptocurrency index
name
string
Name of the cryptocurrency index (e.g., "DeFi", "Smart Contracts")
positive
integer
Total number of positive mentions for all cryptocurrencies in the index
negative
integer
Total number of negative mentions for all cryptocurrencies in the index
neutral
integer
Total number of neutral mentions for all cryptocurrencies in the index
timestamp
number
Unix timestamp representing when this data was collected
date
string
Human-readable date string formatted from the timestamp

API Limits

The Guavy API has a limit of 10 simultaneous connections. You'll receive a 429 error if you reach the limit. At exceptionally high volumes, you may receive an HTTP 429 or 403 without a JSON body.

We recommend that you cache frequently accessed values that do not change often in your application's data store. This will prevent your application from bumping up against the throttling limitations and will likely provide faster access to that data.

Account Limits

Your Guavy account will typically have a licensed limit of at least 100,000 API calls per month. In addition, there is a limit of 100,000 API calls per day. If you reach these limits, you will receive a 429 error.

Connection Timeouts

The Guavy API has a 120-second timeout on API calls. You may see this type of timeout after you've made a network socket connection and are already sending and receiving data.

Response times are dependent on the complexity of your request and the general load across Guavy. Some endpoints in the Guavy API return values that are large and slow to calculate.

Was this helpful?