https://github.com/teklynk/twitch_api_public

Simple PHP Twitch API Gateway that only requires the user/channel name to return data
https://github.com/teklynk/twitch_api_public

api api-gateway api-server twitch

Last synced: 5 months ago
JSON representation

Simple PHP Twitch API Gateway that only requires the user/channel name to return data

• Host: GitHub
• URL: https://github.com/teklynk/twitch_api_public
• Owner: teklynk
• Created: 2022-02-09T06:16:07.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2026-02-15T23:34:11.000Z (5 months ago)
• Last Synced: 2026-02-16T06:48:45.076Z (5 months ago)
• Topics: api, api-gateway, api-server, twitch
• Language: PHP
• Homepage: https://twitchapi.teklynk.com/docs/
• Size: 228 KB
• Stars: 7
• Watchers: 2
• Forks: 2
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml

Awesome Lists containing this project

README

          
# Twitch API Public Gateway

## Overview

This is a way to run your own Twitch API "gate-way" service that only requires the user name/channel name to pull data. It acts as a public gateway to Twitch's API. This is useful when creating your own Twitch tools/apps and just want to get data from Twitch without passing in your client id and auth token into your code and manually refreshing your auth token every 3 months. Auth token automatically refreshes on the server every day. All requests use GET to pull data. Nothing is posted back to Twitch and nothing is stored on the server. Once set up, getting data from Twitch is as simple as going to a URL and parsing the returned JSON string.

## Recent Updates

### June 2024

`getuserclips.php` can now be filtered by "is_featured". This will show clips that the channel has set as Featured.

Example: `https://example.com/getuserclips.php?channel=MrCoolStreamer&prefer_featured=true&limit=100`

### September 2023

Follows and Following endpoint now require a user access token and client ID that includes the `user:read:follows` and/or `moderator:read:followers` scope. This can be generated from twitchtokengenerator.com. The access token and client ID can then be used in the endpoint url: `https://example.com/getuserfollowing.php?channel=MrCoolStreamer&limit=100&ref=accessTokenXyz123Abc&clientId=abc123xyz5678`

The access token and client ID values need to be base_64 encoded.

- javascript: `btoa(stringToEncode);`

- php: `base64_encode(stringToEncode);`

The JSON format for "followers" and "followed" has also changed. Please refer to: Twitch API Reference

## Installation

### Option 1: Using Docker (Recommended)

This branch includes a `Dockerfile` and `docker-compose.yml` to easily run the application locally or on a server.

1.  **Clone the repository:**

    ```bash

    git clone 

    cd twitch_api_public

    ```

2.  **Configure Environment:**

    Rename `sample.env` to `.env` and add your Twitch Client ID and Secret.

    ```bash

    cp sample.env .env

    ```

    *See Configuration below for details on getting Twitch credentials.*

3.  **Build and Run:**

    ```bash

    docker-compose up -d --build

    ```

    This will start the Nginx, PHP-FPM, and Memcached containers.

4.  **Access the API:**

    The API should now be accessible at `http://localhost:8080` (or your server's IP).

**Docker Notes:**

- **Memcached:** If using Docker, ensure `getuserclips.php` is configured to connect to the `memcached` container host instead of `127.0.0.1`.

- **Stopping:** To stop the containers, run `docker-compose down`.

### Option 2: Manual Installation (Bare Metal)

If you prefer not to use Docker, you can run this on a standard LAMP/LEMP stack.

#### 1. Prerequisites

- Linux server (Ubuntu/Debian recommended)

- Nginx or Apache

- PHP 8.1+ (with cURL, XML, mbstring extensions)

- Composer

- Memcached

#### 2. Install Dependencies (Ubuntu Example)

**Install PHP and Extensions:**

```bash

sudo apt update

sudo apt install -y php-fpm php-curl php-xml php-mbstring

```

**Install Memcached:**

```bash

sudo apt install -y memcached php-memcached libmemcached-dev

sudo service memcached start

```

**Install Composer:**

```bash

curl -sS https://getcomposer.org/installer -o composer-setup.php

sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

rm composer-setup.php

```

#### 3. Project Setup

1.  **Clone the repository:**

    ```bash

    cd /var/www/html

    git clone 

    cd twitch_api_public

    ```

2.  **Install PHP Packages:**

    ```bash

    composer install

    ```

3.  **Configure Environment:**

    ```bash

    cp sample.env .env

    ```

    Edit `.env` and add your Twitch credentials.

#### 4. Web Server Configuration

Set the web site's root directory in the nginx/apache config to `/var/www/html/twitch_api_public/public`.

**NGINX Config Example:**

```nginx

server {

    server_name    example.com;

    root           /var/www/html/twitch_api_public/public;

    index          index.php;

    add_header Access-Control-Allow-Origin *;

    # Deny access to . files, for security

    location ~ /\. {

      log_not_found off;

      deny all;

    }

    location / {

      try_files $uri $uri/ =404;

    }

    location ~* \.php$ {

      fastcgi_pass unix:/run/php/php8.1-fpm.sock; # Adjust version as needed

      include         fastcgi_params;

      fastcgi_param   SCRIPT_FILENAME    $document_root$fastcgi_script_name;

      fastcgi_param   SCRIPT_NAME        $fastcgi_script_name;

    }

    # SSL Configuration (Managed by Certbot recommended)

    listen 80;

    listen [::]:80;

}

```

## APACHE Config Example

```apache

   DocumentRoot /var/www/html/twitch_api_public/public

   ServerName example.com;

   ErrorLog ${APACHE_LOG_DIR}/error.log

   CustomLog ${APACHE_LOG_DIR}/access.log combined

   

        Options Indexes FollowSymLinks MultiViews

        AllowOverride All

        Require all granted

   

        DirectoryIndex index.php

        RewriteEngine On

        RewriteCond %{REQUEST_FILENAME} !-d

        RewriteCond %{REQUEST_FILENAME} !-f

        RewriteRule ^[^.]+$ index.php [L]

   

   

   SSLEngine on

   SSLCertificateFile /etc/apache2/certificate/apache2.crt

   SSLCertificateKeyFile /etc/apache2/certificate/private.key

```

## Instructions and Notes

- **Rename** sample.env to .env

- Visit https://dev.twitch.tv/ to register your application. 

- On the dev.twitch.tv site, click "Your Console" in the upper right. Under "Applications" click "Register Your Application". 

- Give your Application a Name.

- OAuth Redirect URLs. When testing locally, you can set this to http://localhost. I like to add localhost and my public domain name entry. This will allow your domain(s) access to the Twitch API. (These domains with this OAuth token and client ID are allowed to access the Twitch API)

- Select Category > Chat Bot.

- Add your Twitch client ID and Twitch secret to the .env file.

These files are needed to generate your Twitch oAuth token.

## Getting data

Requests are returned in JSON format so that you can parse the data as needed. Some requests require a limit parameter in the url and have a max limit of 100.

## Example Requests

Pagination is possible with &after=cursor_value and &before=cursor_value

You can get the cursor value from the first request.

```json

"pagination": {

  "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6Ik1UQXkifX0"

}

```

Example: 

`https://example.com/getuserfollows.php?channel=MrCoolStreamer&limit=100&after=eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6Ik1UQXkifX0`

will pull the next 100 follows.

*Pull a single Random clip with: `&random=true`. Set the `count=3` value to limit how many random clips are returned. If not set, then only 1 random clip is returned.

Example: `https://example.com/getuserclips.php?channel=MrCoolStreamer&limit=100&random=true&count=3`

*Pull a single clip by its ID: id=DelightfulSuaveMacaroniNerfRedBlaster-2Z8TW9kD4d7jN_uy

Example: `https://example.com/getuserclips.php?id=DelightfulSuaveMacaroniNerfRedBlaster-2Z8TW9kD4d7jN_uy`

*Pull only featured clips

Example: `https://example.com/getuserclips.php?channel=MrCoolStreamer&prefer_featured=true&limit=100`

*Ignore / skip newer Twitch clip URLs. `&ignore=new`

## End points examples:

`https://example.com/getuserstatus.php?channel=MrCoolStreamer`

`https://example.com/getuserinfo.php?channel=MrCoolStreamer`

`https://example.com/getstream.php?channel=MrCoolStreamer`

`https://example.com/getuserfollows.php?channel=MrCoolStreamer&limit=100&ref=accesstokenxyz123&clientId=abc123xyz5678`

`https://example.com/getuserfollowing.php?channel=MrCoolStreamer&limit=100&ref=accesstokenxyz123&clientId=abc123xyz5678`

`https://example.com/getuseremotes.php?channel=MrCoolStreamer&limit=100`

`https://example.com/getglobalemotes.php`

`https://example.com/getuserclips.php?channel=MrCoolStreamer&limit=100`

`https://example.com/getuserclips.php?channel=MrCoolStreamer&limit=100&start_date=2023-02-15T00:00:00Z&end_date=2023-02-24T00:00:00Z&creator_name=MrCoolStreamer`

`https://example.com/getuserclips.php?channel=MrCoolStreamer&prefer_featured=true&limit=100`

`https://example.com/getviewers.php?channel=MrCoolStreamer`

`https://example.com/getgame.php?id=23123`

`https://example.com/getuserschedule.php?channel=MrCoolStreamer`

`https://example.com/getuserschedule.php?channel=MrCoolStreamer&ical=true` - returns .ics download file that can imported into a calendar client.

`https://example.com/getuserschedule.php?channel=MrCoolStreamer&html=true&format=0&limit=30` - returns html view (format=1 is an alternate date/time format). Event dates and times have been converted to your local time zone. This could be used as a OBS browser source or embedded as an iframe on a website.

`https://example.com/getbttvemotes.php?channel=MrCoolStreamer`

**Most endpoints can use 'id' instead of 'channel'. Examples: `https://example.com/getuserinfo.php?id=55184769`, `https://example.com/getuserstatus.php?id=55184769`, `https://example.com/getuserschedule.php?id=55184769`**

jQuery Ajax Example:

```javascript

let channel = "MrCoolStreamer";

$.ajax({url: "https://example.com/getuserinfo.php?channel=" + channel, success: function(result) {

	console.log(result);

}});

// Example2: Json data - Ajax call

let clips_json = JSON.parse($.getJSON({

	'url': "https://example.com/getuserclips.php?channel=" + channel + "&limit=100",

	'async': false

}).responseText);

console.log(clips_json.data[0]['thumbnail_url']);

```

JavaScript Example:

```javascript

let getUserInfo = function (channel) {

    let url = "https://example.com/getuserinfo.php?channel=" + channel;

    return fetch(url)

        .then(response => response.json());

};

getUserInfo("MrCoolStreamer").then(result => {

	console.log(result);

});

```

CURL Example:

```bash

curl -X GET 'https://example.com/getuserinfo.php?channel=MrCoolStreamer'

```

PHP using CURL Example:

```php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://example.com/getuserinfo.php?channel=MrCoolStreamer");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($ch);

curl_close($ch);

var_dump($result);

```

Example Responses:

```json

{

  "data": [

    {

      "id": "141981764",

      "login": "mrcoolstreamer",

      "display_name": "MrCoolStreamer",

      "type": "",

      "broadcaster_type": "partner",

      "description": "Supporting third-party developers building Twitch integrations from chatbots to game integrations.",

      "profile_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/8a6381c7-d0c0-4576-b179-38bd5ce1d6af-profile_image-300x300.png",

      "offline_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/3f13ab61-ec78-4fe6-8481-8682cb3b0ac2-channel_offline_image-1920x1080.png",

      "view_count": 5980557,

      "created_at": "2016-12-14T20:32:28Z"

    }

  ]

}

```

## Clips

getuserclips.php

```json

{

  "data": [

    {

      "item": 22,

      "id": "VictoriousAwkwardPheasantKevinTurtle-xT8tH7fW0oU0vZ8gT4",

      "url": "https://clips.twitch.tv/VictoriousAwkwardPheasantKevinTurtle-xT8tH7fW0oU0vZ8gT4",

      "embed_url": "https://clips.twitch.tv/embed?clip=VictoriousAwkwardPheasantKevinTurtle-xT8tH7fW0oU0vZ8gT4",

      "broadcaster_id": "159805577",

      "broadcaster_name": "Teklynk",

      "creator_id": "141981764",

      "creator_name": "MrCoolStreamer",

      "video_id": "",

      "game_id": "509670",

      "language": "en",

      "title": "I don't know what is happening",

      "view_count": 1,

      "created_at": "2022-08-08T17:33:04Z",

      "thumbnail_url": "https://clips-media-assets2.twitch.tv/_tduXpTTRFVsBuTb_XYZABC/vod-1543945678-offset-4866-preview-480x272.jpg",

      "duration": 30,

      "vod_offset": null,

      "clip_url": "https://clips-media-assets2.twitch.tv/_tduXpTTRFVsBuTb_XYZABC/vod-1543945678-offset-4866.mp4"

    }

  ]

}

```

## BetterTTV Emotes

getbttvemotes.php

```json

[

  {

    "id": "636ff60fb9076d0aaebbcf7c",

    "code": "Tekbot"

  },

  {

    "id": "5ba6d5ba6ee0c23989d52b10",

    "code": "bongoTap"

  },

  {

    "id": "5a6edb51f730010d194bdd46",

    "code": "PepoDance"

  },

  {

    "id": "5d922afbc0652668c9e52ead",

    "code": "peepoArrive"

  },

  {

    "id": "59f06613ba7cdd47e9a4cad2",

    "code": "PartyParrot"

  },

  {

    "id": "5c3427a55752683d16e409d1",

    "code": "peepoPooPoo"

  },

  {

    "id": "5bc7ff14664a3b079648dd66",

    "code": "peepoRun"

  },

  {

    "id": "5df2d1b7e7df1277b6070b1e",

    "code": "pepeJAM"

  },

  {

    "id": "5f21e57a65fe924464eecf0e",

    "code": "catRAVE"

  },

  {

    "id": "54fa8f1401e468494b85b537",

    "code": ":tf:"

  }

]

```

BTTV Emote URL: https://cdn.betterttv.net/emote/5a970ab2122e4331029f0d7e/3x