Clash of Clans – How to use the Web API

I originally wrote this on my site, https://blog.crazy.technology, which I will be taking down in a few days.

This post will cover the basics to make API calls to COC from a web server.


Be the first to see our articles. Follow us on Facebook ❤️


Where there are code snippets included, I will try to include comments/explanations to help non-programmers follow along.

You will need:

[UPDATE from forum]: For a novice, he can simply create an account at a free provider because installing a web server on his own machine is already complicated. It will be confronted with firewall concerns and also non static ip address … In short, a free account and filezilla is much simpler by example https://infinityfree.net/

Notger

What this post does not cover:

  • Saving the data recieved from the API
  • Web site design
  • Basic programming skills

For a full working example, see my project, Clash Dash or view the source code on Github.


Be the first to see our articles. Follow us on Facebook ❤️


1. Register for a COC Dev Account

Head over to https://developer.clashofclans.com to sign up for an account if you don’t have one.

2. Get a JWT Token

A Brief Overview (skip if you just want to get it to work)

COC uses JSON Web Tokens (JWT) to authenticate calls to their Web API.

JSON

  • JavaScript Object Notation (basically a javascript object made into a standardized string)

JSON Web Tokens

  • Used to authenticate calls from you to the API server
  • You don’t need to know the specifics of these, but it is designed to be read-only on the client end. Modifications will break the token, and cause the authentication to fail.
  • Find out more from JWT’s official site https://jwt.io/

Steps

Click on your name (top-right hand corner) > My Account > Create a new key to get started.

Navigating to My Account

Enter a Key Name, Description and the IP addresses you will be using this API key from.
Get your public IP address from Google.

screen cap
Creating an API key

IMPORTANT: COC’s API authentication is tied to your IP address. Most residential IP addresses are * DYNAMIC (not static)*, meaning they change from time to time.

This also means that the token issued by COC will eventually throw authentication errors, and stop working. This happens when your ISP shuffles the IP addresses for you. You can simply create another key when that happens.

You will need to either get a static IP address or web hosting, which will not be covered in this article.

Your API key will contain the following details:

Viewing your API key

3. Making calls to the API

The documentation shows all the API end-points, but does not state the base URL outright.
It is: https://api.clashofclans.com/v1

end points
API end-points from documentation

Thus, to make an API call, the complete URL is:

Base URL (https://api.clashofclans.com/v1) + (/endpoint)

If the endpoint is “/clans/{clanTag}/members”, you will need to substitute the {clanTag} with your actual clan tag. For PHP, use urlencode($clantag) to get a properly formatted clan tag.

PHP code

The code below provides working snippet for you to use on your web server. Importantly, the following needs to be changed:

  • $token – Swap in your own token here
  • $clantag – Swap in your clan tag here

To use: Save the file with the extension ‘.php’ to the web server. (Eg. clash-example.php)

  • For Windows’ IIS, it is in C:\inetpub\wwwroot
  • For Apache (linux), it is in /var/www/html
<?php
header('Content-Type: application/json; charset=UTF-8');// sets response headers

$clantag = "#2PCCRLYP"; // Your clan tag here

$token = "eyJ0eXAiOiJKV1Q...JcwHWKQ"; // Your token here

//URL for api calls
$url_api_base = "https://api.clashofclans.com/v1";
$url_clan = $url_api_base."/clans/" . urlencode($clantag);
//Create a new CURL
$ch = curl_init($url_clan);

//Sets headers and options for CURL
$headr = array();
$headr[] = "Accept: application/json";
$headr[] = "Authorization: Bearer ".$token;
curl_setopt($ch, CURLOPT_HTTPHEADER, $headr);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); 

//Executes and terminates request
$res = curl_exec($ch);
$clan_data_arr = json_decode($res, true);
curl_close($ch);

//prints out data obtained from CURL request. Remove this line and implement your own logic
echo json_encode($clan_data_arr);

Then, in your internet browser, navigate to http://localhost/{file-name}.php (eg. http://localhost/clash-example.php)

If you’re successful, the echo json_encode($clan_data_arr) should produce the following:

{
"tag":"#2PCCRLYP",
"name":"Night Warriors",
"type":"inviteOnly",
"description":"\u2b50\ufe0fLoyalty to Royalty\u2b50\ufe0f Telegram required for coleaders. Keep the environment friendly. Make both war attacks and keep your war status actively updated.",
"location":{
"id":32000006,
"name":"International",
"isCountry":false
}, 
// etc...

You are likely to run into errors when you run the script above due to missing modules/configuration. Enable error-reporting by placing these lines after the header in line 1 of the php file.

ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);

Google your errors to quickly find out how to enable fix them.

Recommendations

Because you are likely to be serving a large group of web users, I highly recommend not to call COC’s API on page load. They block repeated calls to their servers, so you should schedule your calls at nice, friendly intervals and save that data on your own server.

Of course, if you’re simply calling one API per user action, it should not be an issue. The problem will arise if you try to, for example, get full player data for every member in the clan, all at once.

You may also run into this problem if your site receives a lot of traffic.

Some options are to save them as a file (see my Github project) or on a database. These are beyond the scope of this article, and will not be covered here.

If there is interest, drop me a comment below, give me a like or follow me on Facebook, and I will work on saving data into a database in the near future.

Cheers 🙂

Supercell Disclaimer: This content is not affiliated with, endorsed, sponsored, or specifically approved by Supercell and Supercell is not responsible for it. For more information see Supercell’s Fan Content Policy: www.supercell.com/fan-content-policy.

Support our Contributors. They get a little something for every new Like we get ❤️