Neverending Programming Mistakes

    TypeScript icon, indicating that this package has built-in type declarations

    1.0.2 • Public • Published


    npm Travis (.org)

    Count API logo

    This is the official promise-based wrapper for CountAPI. CountAPI is a free counting service, you can use it to track page hits, and custom events.


    npm install countapi-js --save


    First, include the package

    const countapi = require('countapi-js');
    // or with ES6
    import countapi from 'countapi-js';

    Counting the number of visits per page

    countapi.visits().then((result) => {

    Refresh the page multiple times and check the console!

    If you want to track the number of visits through the whole site instead

    countapi.visits('global').then((result) => {

    Or custom events

    document.getElementById("magic-button").addEventListener("click", () => {
      countapi.event('magic-button').then((result) => {
        alert(`The magic button has been pressed ${result.value} times.`);

    Keys and namespaces

    Namespaces are meant to avoid name collisions. Its recommend use the domain of the application as namespace to avoid collision with other websites. By default, the visits and event functions will use the current domain as namespace and the provided arguments as key. If the namespace is not specified the key is assigned to the default namespace.

    Keys and namespaces must match ^[A-Za-z0-9_-.]{3,64}$.

    Available methods

    ℹ️ Note: When requesting existing keys, if the key doesn't exists the status returned will be 404 (the promise will not fail).


    countapi.get(namespace, key)

    Get the value of a key.

    countapi.get('', 'test').then((result) => { ... });

    result may look like

        status: 200,
        path: "",
        value: 136


    countapi.set(namespace, key, value)
    countapi.set(key, value)

    Set the value of a key.

    ℹ️ Note: To set a key, it must be created with enable_reset set to true.

    countapi.set('', 'test', 42).then((result) => { ... });

    result may look like

        status: 200,
        path: "",
        old_value: 136,
        value: 42

    ℹ️ Note: If the key has enable_reset set to false, status will be 403 and the old_value will match value (the key stays the same), also the promise will NOT fail.


    countapi.update(namespace, key, amount)
    countapi.update(key, amount)

    Updates a key with +/- amount.

    ℹ️ Note: amount must be within update_lowerbound and update_upperbound specified during the creation of the key.

    // subtract 3
    countapi.update('', 'test', -3).then((result) => { ... });

    result may look like

        status: 200,
        path: "",
        value: 42

    ℹ️ Note: If the amount provided is invalid you will get status 403.


    countapi.hit(namespace, key)

    A shorthand for update with amount=1. And useful if you don't want to create a key manually, since if you request a key that doesn't exists, a key with enable_reset=false, update_lowerbound=0 and update_upperbound=1 will be created automatically.

    countapi.hit('', 'visits').then((result) => { ... });

    result may look like

        status: 200,
        path: "",
        value: 27

    visits / event

    countapi.visits(page) countapi.event(name)

    Useful shorthands for hit using as namespace the current hostname. For .visits you may pass page to provide your own page identifier. If page is not provided it will be extracted from the current URL. For .event you have to pass a event name.

    Examples for those are shown in the example section.



    Create a key. All parameters are optional.

    name default description
    key New UUID Name of the key
    namespace default Namespace to store the key
    value 0 The initial value
    enable_reset 0 Allows the key to be resetted with set
    update_lowerbound -1 Restrict update to not subtract more than this number. This number must be negative or zero.
    update_upperbound 1 Restrict update to not add more than this number. This number must be positive or zero.
    countapi.create(options).then((result) => { ... });

    result may look like

        status: 200,
        path: "default/6d5891ff-ebda-48fb-a760-8549d6a3bf3a",
        namespace: "default",
        key: "6d5891ff-ebda-48fb-a760-8549d6a3bf3a",
        value: 0

    If there is a problem creating the key, the promise will be rejected with meaningful information.

    info, key)

    Retrive information about a key.'test').then((result) => { ... });

    result may look like

        status: 200,
        path: "default/test",
        namespace: "default",
        key: "test",
        ttl: 15769998014,
        created: 1553794487479,
        update_lowerbound: 0,
        update_upperbound: 1,
        enable_reset: false,
        value: 69



    Get some CountAPI stats.

    countapi.stats().then((result) => { ... });

    result may look like

        keys_created: 111111,
        keys_updated: 111111,
        requests: 111111,
        version: "xxxxxx"

    Further documentation

    Visit for the full API documentation.


    npm test





    npm i countapi-js

    DownloadsWeekly Downloads






    Unpacked Size

    21.3 kB

    Total Files


    Last publish


    • mlomb
    • apilayer-admin