MENU navbar-image

Introduction

A free, public JSON API for the PHP community.

Everything here is public, read-only and needs no API key. Herds marked private by their owner are excluded from every endpoint.

The machine-readable spec lives at /docs.openapi. Country codes are ISO 3166-1 alpha-3 (DNK, GBR, BRA).

Be kind to the herd: cache what you fetch rather than re-reading the whole catalogue.

Authenticating requests

This API is not authenticated.

Countries

Which countries have public collectors, and how many.

List countries with public collectors

Returns every country that has at least one public herd, with its alpha-3 code, name and collector count, ordered by collector count descending then name ascending. Use this to discover which country codes are worth passing to /ranking or /herd/{username} lookups, instead of scraping the ranking page's country selector.

Example request:
curl --request GET \
    --get "https://elephpant.me/api/countries" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://elephpant.me/api/countries"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (503):

Show headers 
cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *
 

{
    "message": "Service Unavailable"
}

Request      

GET api/countries

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Response

Response Fields

countries   object     
code   string     

ISO 3166-1 alpha-3 country code.

collectors   integer     

Number of public herds registered in this country.

Elephpants

The elePHPant species catalogue and per-species ownership stats.

List all elephpants

Returns a paginated list of all elephpant species, ordered by year and name.

Example request:
curl --request GET \
    --get "https://elephpant.me/api/elephpants?page=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://elephpant.me/api/elephpants"
);

const params = {
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (503):

Show headers 
cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *
 

{
    "message": "Service Unavailable"
}

Request      

GET api/elephpants

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

page   integer  optional    

Page number. Example: 1

Response

Response Fields

data   object     
owners   integer     

Number of collectors that have at least one of this elePHPant in their herd.

copies   integer     

Every copy held across all herds, including spares (SUM of quantity, not distinct owners).

ownership_percentage   number     

Percentage of all collectors who own at least one of this elePHPant, rounded to 2 decimals.

updated_at   string     

When this species' catalogue entry (name, description, image) last changed.

Get a single elePHPant

Example request:
curl --request GET \
    --get "https://elephpant.me/api/elephpants/1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://elephpant.me/api/elephpants/1"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (503):

Show headers 
cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *
 

{
    "message": "Service Unavailable"
}

Request      

GET api/elephpants/{id}

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

elePHPant ID. Example: 1

Herds

A single collector's herd of elePHPants.

Get a collector's herd

Returns the full herd of a registered collector, including statistics and collected elePHPants. 403s if the herd is private.

Example request:
curl --request GET \
    --get "https://elephpant.me/api/herd/john" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://elephpant.me/api/herd/john"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (503):

Show headers 
cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *
 

{
    "message": "Service Unavailable"
}

Request      

GET api/herd/{username}

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

username   string     

Collector username. Example: john

Response

Response Fields

country   string     

ISO 3166-1 alpha-3 country code.

updated_at   string     

When the collector last updated their herd (add, remove or change a quantity). Null if the herd is empty.

stats   object     
total   integer     

Total elePHPants held, including spares.

unique   integer     

Distinct elePHPant species held.

spare   integer     

Extra copies beyond one of each species held (total - unique).

elephpants   object     
quantity   integer     

How many of this elePHPant the collector owns.

Ranking

Collector leaderboards, globally or scoped to a country.

List the top collectors

Returns public herds ranked by number of unique elePHPants, then by total elePHPants, then alphabetically by name. rank is the position in the full ordering (not page-relative), and updated_at is an exact timestamp, not a rendered relative string, so it stays accurate however long you hold onto the response.

Example request:
curl --request GET \
    --get "https://elephpant.me/api/ranking?country=GBR&page=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://elephpant.me/api/ranking"
);

const params = {
    "country": "GBR",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (503):

Show headers 
cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *
 

{
    "message": "Service Unavailable"
}

Request      

GET api/ranking

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

country   string  optional    

ISO 3166-1 alpha-3 country code to filter the ranking by. Example: GBR

page   integer  optional    

Page number. Example: 1

Response

Response Fields

data   object     
rank   integer     

Position in the full ordering, not relative to the current page.

stats   object     
spare   integer     

Extra copies beyond one of each species held (total - unique).

updated_at   string     

When this collector last updated their herd. Null if the herd is empty.