Getting started overview

CountAPI provides a straightforward HTTP API for tracking counts without requiring user authentication or API keys. This design facilitates rapid integration for basic counting needs, such as website page views, button clicks, or simple event tracking. The service operates on a free tier, subject to rate limits to ensure fair usage across all consumers.

To get started with CountAPI, the primary steps involve understanding its endpoint structure and executing a simple HTTP GET request. The API supports operations to get a count, set a count, or update a count by incrementing or decrementing it. Each count is associated with a unique namespace and key, allowing developers to manage multiple counters within their applications. The simplicity of CountAPI makes it suitable for projects where minimal setup and quick deployment are priorities, and where advanced analytics or robust security features are not primary requirements.

Here’s a quick reference for the initial setup:

Step What to do Where
1. Understand API Structure Review the basic concepts of namespaces and keys. CountAPI API reference
2. No Account Creation No signup or login is required to use CountAPI. N/A
3. No API Keys Authentication is not used; API keys are not needed. N/A
4. Make First Request Construct a simple HTTP GET request to retrieve a count. Your preferred HTTP client (e.g., browser, curl, application code)
5. Increment Counter Send an HTTP GET request to increment a counter. Your preferred HTTP client

Create an account and get keys

CountAPI does not require users to create an account or obtain API keys. The service is designed for immediate use without any registration process. This approach simplifies integration, as developers can begin making requests to the API endpoints directly once they understand the basic URL structure for managing counters. The absence of authentication means that all requests are public, and security relies on obscurity of the chosen namespace and key for non-critical applications. For applications requiring secure, authenticated access or advanced access control, alternative solutions like OAuth 2.0 or API gateway authentication (e.g., Kong Gateway) would be necessary.

To manage your counters, you will define a unique namespace and a key. These act as identifiers for your specific counter. For example, if you want to track page views for your website example.com, you might use example.com as the namespace and pageviews as the key. The combination of these two elements uniquely identifies your counter within the CountAPI system. Since there are no accounts, there is no dashboard or portal to manage these counters centrally; management is done entirely through API calls.

Your first request

Making your first request with CountAPI involves constructing a simple HTTP GET request. There are several endpoints available, but the most common to start with are /get and /hit. The /get endpoint retrieves the current value of a counter, while the /hit endpoint increments a counter by one and returns its new value.

Structure of a CountAPI URL

CountAPI URLs follow a consistent structure:

https://api.countapi.xyz/<endpoint>/<namespace>/<key>
  • <endpoint>: The operation you want to perform (e.g., get, hit, set, update).
  • <namespace>: A unique identifier for a group of counters. This could be your website domain, application name, or any string that logically groups your counters.
  • <key>: A unique identifier for a specific counter within that namespace.

Example: Getting a counter's value

To retrieve the current value of a counter, use the /get endpoint. If the counter does not exist, it will be initialized to 0 and returned.

curl https://api.countapi.xyz/get/mywebsite.com/pageviews

A successful response will look like this:

{
  "value": 123
}

Example: Incrementing a counter (hit)

To increment a counter by one, use the /hit endpoint. This is commonly used for tracking page views or button clicks. If the counter does not exist, it will be initialized to 1 and returned.

curl https://api.countapi.xyz/hit/mywebsite.com/pageviews

A successful response will return the new value:

{
  "value": 124
}

Example: Setting a counter's value

You can also explicitly set a counter to a specific value using the /set endpoint. This requires an additional query parameter value.

curl https://api.countapi.xyz/set/mywebsite.com/downloads?value=500

The response will confirm the new value:

{
  "value": 500
}

Example: Updating a counter by a specific amount

To increment or decrement a counter by an amount other than one, use the /update endpoint with a delta query parameter.

# Increment by 10
curl https://api.countapi.xyz/update/mywebsite.com/items_in_cart?delta=10

# Decrement by 5
curl https://api.countapi.xyz/update/mywebsite.com/items_in_cart?delta=-5

The response will show the updated value:

{
  "value": 105
}

Common next steps

After successfully making your first requests, consider these common next steps to integrate CountAPI more deeply into your applications:

  1. Integrate into your frontend: For web applications, you can embed CountAPI calls directly into your JavaScript. For example, to track page views, you might add a script that calls the /hit endpoint when the page loads. Remember that these requests are public and visible in browser developer tools.
  2. Integrate into your backend: For server-side applications, you can use any HTTP client library in your chosen programming language to interact with CountAPI. This is useful for tracking internal events or actions that shouldn't be exposed directly to client-side code.
  3. Choose descriptive namespaces and keys: While CountAPI doesn't enforce naming conventions, using clear and descriptive namespaces (e.g., your domain, application name) and keys (e.g., homepage_visits, button_clicks) will help you manage your counters more effectively.
  4. Monitor rate limits: Although CountAPI offers an unlimited free tier, it is subject to rate limiting. While specific limits are not publicly documented, excessive requests from a single source may result in temporary blocking. Implement basic error handling and consider caching strategies for frequently accessed, slowly changing counts to reduce API call volume.
  5. Explore advanced usage: Review the CountAPI documentation for details on other endpoints, such as retrieving multiple counts in a single request or resetting counters.
  6. Consider alternatives for critical applications: For production applications requiring high availability, guaranteed performance, advanced analytics, or secure, authenticated access, consider more robust solutions. Options include building a custom counter service using a database like Redis, or leveraging cloud-based solutions such as Google Firebase Realtime Database or AWS DynamoDB, which offer more control and scalability.

Troubleshooting the first call

When making your first calls to CountAPI, you might encounter a few common issues. Here’s how to troubleshoot them:

  • 404 Not Found:

    • Issue: This usually means the URL path is incorrect.
    • Solution: Double-check the endpoint, namespace, and key in your URL. Ensure there are no typos and that the structure matches https://api.countapi.xyz/<endpoint>/<namespace>/<key>. Refer to the CountAPI API reference for correct endpoint names.

  • Network Errors (e.g., Connection Refused, Timeout):

    • Issue: Your client cannot reach the CountAPI server.
    • Solution: Verify your internet connection. If you are behind a corporate firewall or proxy, ensure that outgoing connections to api.countapi.xyz on port 443 (HTTPS) are permitted. Temporary service outages can also cause this, so try again after a few minutes.

  • Incorrect Response Format (not JSON):

    • Issue: The API always returns JSON. If you receive plain text or an HTML error page, something is wrong with the request or the service.
    • Solution: This often points to a malformed URL or an internal server error on CountAPI's side. Check your URL for any non-standard characters or formatting issues.

  • Rate Limiting (No explicit error code, but requests stop working):

    • Issue: While CountAPI doesn't typically return a specific rate limit error code, excessive requests in a short period might lead to your requests being silently dropped or temporarily blocked.
    • Solution: Reduce the frequency of your API calls. For high-volume scenarios, consider implementing client-side caching for counts that don't need to be updated in real-time on every single request. For example, update a page view counter every 5-10 seconds instead of on every page load.

  • Cross-Origin Resource Sharing (CORS) Issues (in browser environments):

    • Issue: When calling CountAPI from a web browser, you might encounter CORS errors if your website is not hosted on a domain that CountAPI explicitly allows for direct cross-origin requests.
    • Solution: CountAPI generally supports CORS for simple GET requests. If you encounter issues with more complex requests (e.g., non-GET, custom headers), you might need to proxy the CountAPI requests through your own backend server to bypass browser CORS restrictions. For more information on CORS, consult the MDN Web Docs on CORS.