Readme.md

Readme

Online Version @ Github: https://github.com/frontimax/football-butler/blob/main/README.md

This gem enables API requests against multiple different football APIs, with direct requests or using normalized endpoint Class methods. Currently supported APis:

  • football-data.org
  • apifootball.com

To use the API you need an API token, get it for free @ http://api.football-data.org/register or https://apifootball.com/register.

Depending on you Payment Plan you can access international Competitions, Teams, Matches, Scores, Players, Odds, and Standings.

Also see the following Links:

www.football-butler.de (Offical Gem Homepage)
www.code-butler.de (More Projects & Solutions with Rails & Flutter)
Twitter/code_butler

Tiers

This Gem supports two ways of using the APIs:

  • direct calls to the API with path & filters
  • “comfort” functions (one class for each endpoint with semantic methods)

Update May 2021 (v2.0.0): Multiple APIs are now supported and all endpoints for football-data.org are now implemented. See below for more info on usage.

Update April 10th 2021: The Tier packages have been adjusted – Standings are now part of TIER_ONE and also of the newest Gem Version 1.1.0

Installation

Add this line to your application’s Gemfile:

gem 'football-butler'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install football-butler

Configuration

The quickest way to start

Note: football-data.org (api_name: :football_data_org) ist set as the default API.

To use the API you need to configure the API token.
You can do this “on the fly” or in your application configuration:

Initializer

Create your own initializer file config\initializers\football_butler.rb and add:

Football::Butler::Configuration.configure do |config|
  config.api_token = "<YOUR_API_TOKEN_HERE>"
end

On the Fly

As a function (use this line first in the rails console if you dont use the above initilaizer!)

Football::Butler.Configure.reconfigure(
  api_token: "<YOUR_API_TOKEN_HERE>"
)

Get you first data from the rails console

Get all matches of current Bundesliga season:

rails c
Football::Butler::Matches.by_competition(id: 2002)

Change the target API

See the available api names:

Football::Butler::Configuration::AVAILABLE_APIS
[:football_data_org, :apifootball_com]

To set the target API:

Football::Butler::Configuration.configure do |config|
  config.api_name  = :apifootball_com
  config.api_token = "<YOUR_API_TOKEN_HERE>"
end

To change the target API:

Football::Butler.Configure.reconfigure(
  api_name:  :apifootball_com
  api_token: "<YOUR_API_TOKEN_HERE>"
)

The advanced way to go (more options)

Available Configuration Values

NameDefault ValueData TypeExplanation
api_tokennilStringYour API Token (required to set by you)
api_name:football_data_orgStringmust be one of: [:football_data_org, :apifootball_com]
api_version2IntegerAPI Version
api_endpointhttps://api.football-data.org/v#{api_version}StringAPI Endpoint
tier_plan
ONLY: :football_data_org
nilStringTIER_ONE
TIER_TWO
TIER_THREE
TIER_FOUR
wait_on_limit
ONLY: :football_data_org
falseBooleanUses ‘sleep’ to wait if request is limited

The tier_plan is only used in Football::Butler::Competitions.all as a default filter. You can use “plan” filter manually on Competition calls.

Example

Football::Butler::Configuration.configure do |config|
  config.api_token  = "<YOUR_API_TOKEN_HERE>"
  config.api_version = 2
  config.api_endpoint = "https://api.football-data.org/v2"
  config.tier_plan = 'TIER_TWO'
  config.wait_on_limit = true
end

or

Football::Butler.Configure.reconfigure(
  api_token: "<YOUR_API_TOKEN_HERE>",
  api_version = 2,
  api_endpoint = "https://api.football-data.org/v2",
  tier_plan = 'TIER_TWO',
  wait_on_limit = true
)

Usage

Direct API Calls with path and filters

football_data_org

Example:

# Resources
# https://www.football-data.org/documentation/quickstart#available-resources
path = 'competitions/BL1/matches' # (or path = 'competitions/2002/matches')

# Filtering
# https://www.football-data.org/documentation/quickstart#filtering
filters = { matchday: 1 }

response = Football::Butler.get(path: path, filters: filters)

Will call

http://api.football-data.org/v2/competitions/BL1/matches?matchday=1

and return all matches of match day 1 of the german Bundesliga, current season:

response['count'] 
=> 9

response['filters']
=> {"matchday"=>"1"}

response['competition']
=> {"id"=>2002, "area"=>{"id"=>2088, "name"=>"Germany"}, "name"=>"Bundesliga", ... }

response['matches']
=> [{"id"=>303007, "season"=>{"id"=>599, "startDate"=>"2020-09-18", "endDate"=>"2021-05-15", "currentMatchday"=>27}, "utcDate"=>"2020-09-18T18:30:00Z", "status"=>"FINISHED", ...}]

If you performed a bad request, e.g. invalid api_token configured, you will get an error hash:

response['message']
=> "Your API token is invalid."

response['errorCode']
=> 400

apifootball_com

Example:

# Resources
# https://apifootball.com/documentation
path = 'action=get_events'

filters = { league_id: 149, from: '2021-05-16', to: '2021-05-16' }

response = Football::Butler.get(path: path, filters: filters)

Will call

https://apiv2.apifootball.com/?action=get_events&from=2021-05-16&to=2021-05-16&league_id=149&APIkey=<YOUR_API_TOKEN>

and return all matches of 2021-05-16 of the english Premiere League for the given time range:

response.parsed_response
=> [{"match_id"=>"497362", "country_id"=>"41", "country_name"=>"England", "league_id"=>"149", "league_name"=>"Championship", ....]

If you performed a bad request, e.g. invalid api_token configured, you will get an error hash:

response['message']
=> "No event found (please check your plan)!"

Comfort Functions (Endpoint Classes)

Instead of using the direct API calls you can use endpoint classes with semantic methods to get results. This list may be expanded in future versions.

I tried to normalize endpoint classes (with aliases) and methods across different target APIs. If an endpoint class is not available (such as Predictions and Statistics in API :football_data_org) you will get an error message:

"The Endpoint 'Predictions' is not supported by this API: football_data_org"

If a method is not available for that target API, you will also get an error message:

"Method 'by_name' is not supported for the endpoint 'Countries' by this API: apifootball_com"

NOTE: I did not normalize the returned data-types yet as I wanted to keep straight with the target API. Let me know if you would like to have a Configuration option to return same data types for all returns and target APIs. Until then: use “result: :default” where available and work with the normalized HTTParty Response Type.

football_data_org

Most methods return the result directly (e.g. :matches), but you can also get the complete HTTParty response (as shown above in the direct API call) by using the “result: :default” option:

Directly returns an Array with all areas:

Football::Butler::Areas.all
=> [{"id"=>2000, "name"=>"Afghanistan", "countryCode"=>"AFG", "ensignUrl"=>nil, "parentAreaId"=>2014, "parentArea"=>"Asia"}, ... ]

Returns a Hash with full API response:

response = Football::Butler::Areas.all(result: :default)
=> response.keys
=> ["count", "filters", "areas"]
=> response['areas']
=> [{"id"=>2000, "name"=>"Afghanistan", "countryCode"=>"AFG", "ensignUrl"=>nil, "parentAreaId"=>2014, "parentArea"=>"Asia"}, ... ]

If you request a single Object (e.g. “by_id”) the Object is returned by football-data.org directly as a Hash (not in an Array)! Exception: Match.by_id returns Hash with Keys [“head2head”, “match”]

Note: You can also use “Countries”, as this is an alias Class from :apifootball_com.

apifootball_com

Most methods return the result directly (result: :parsed_response), but you can also get the complete HTTParty response (as shown above in the direct API call) by using the “result: :default” option:

Directly returns an Array with all areas:

Football::Butler::Countries.all
=> [{"country_id"=>"41", "country_name"=>"England", "country_logo"=>"https://apiv2.apifootball.com/badges/logo_country/41_england.png"}, {"country_id"=>"46", "country_name"=>"France", "country_logo"=>"https://apiv2.apifootball.com/badges/logo_country/46_france.png"}]

Returns a full API response:

response = Football::Butler::Countries.all(result: :default)
=> response.parsed_response
=> [{"country_id"=>"41", "country_name"=>"England", "country_logo"=>"https://apiv2.apifootball.com/badges/logo_country/41_england.png"}, {"country_id"=>"46", "country_name"=>"France", "country_logo"=>"https://apiv2.apifootball.com/badges/logo_country/46_france.png"}]
=> response.code
=> 200

Note: You can also use “Areas”, as this is an alias Class from :football_data_org.

Overview of all available Endpoint Classes

Classfootball-data.orgapifootball.com
AreasYESYES
alias from Countries
CompetitionsYESYES
CountriesYES
alias from Areas
YES
EventsYES
alias from Matches
YES
HeadToHeadYESYES
LineupsYESYES
MatchesYESYES
alias from Events
OddsYESYES
PlayersYESYES
PredictionsNOYES
ScorersYESYES
alias from TopScorers
StandingsYESYES
StatisticsNOYES
TeamsYESYES
TopScorersYES
alias from Scorers
YES

Areas

Football::Butler::Areas

alias (apifootball_com): Football::Butler::Countries

Return Values for football-data & apifootball if the result option is not set explicitly!

MethodParams requiredParams optionalfootball-dataapifootball
by_idid: IntegerHTTParty::Response (Hash)N/A
allresult (Symbol)ArrayArray
by_namename: StringHTTParty::Response (Hash)N/A

Examples:

Football::Butler::Areas.by_id(id: 2088)
Football::Butler::Areas.all
Football::Butler::Areas.by_name(name: 'Germany')

Football::Butler::Countries.all

Competitions

Football::Butler::Competitions

Return Values for football-data & apifootball if the result option is not set explicitly!

MethodParams requiredParams optionalfootball-dataapifootball
by_idid: IntegerHTTParty::Response (Hash)N/A
by_countryid: IntegerN/AArray
allresult (Symbol)
filters (Hash)
ArrayArray
by_planplan: Stringresult (Symbol)
filters (Hash)
ArrayN/A
by_areasids: Arrayresult (Symbol)
filters (Hash)
ArrayN/A
current_match_dayid: IntegerIntegerN/A
seasonsid: IntegerArrayN/A

Examples:

Football::Butler::Competitions.by_id(id: 2002)
Football::Butler::Competitions.all(filters: { plan: 'TIER_ONE' })
Football::Butler::Competitions.by_plan(plan: 'TIER_ONE')
Football::Butler::Competitions.by_areas(ids: [2088, 2081])
Football::Butler::Competitions.current_match_day(id: 2002)
Football::Butler::Competitions.seasons(id: 2002)

Football::Butler::Competitions.by_country(id: 44)

Countries

Football::Butler::Countries

NOTE: alias of/see Football::Butler::Areas

Events

Football::Butler::Events

NOTE: alias of/see Football::Butler::Matches

HeadToHead (added in version 2.0.0)

Football::Butler::HeadToHead

Return Values for football-data & apifootball if the result option is not set explicitly!

MethodParams requiredParams optionalfootball-dataapifootball
by_matchid: IntegerHashN/A
by_teamsteam_id: Integer
second_team_id
result (Symbol)
filters (Hash)
N/AHash

Examples:

Football::Butler::HeadToHead.by_match(id: 2002)

Football::Butler::HeadToHead.by_teams(team_id: 7275, second_team_id: 151)

Lineups (added in version 2.0.0)

Football::Butler::Lineups

Return Values for football-data & apifootball if the result option is not set explicitly!

MethodParams requiredParams optionalfootball-dataapifootball
by_matchid: IntegerHashHash

Examples:

Football::Butler::Lineups.by_match(id: 2002)

Matches

Football::Butler::Matches

alias (apifootball_com): Football::Butler::Events

Return Values for football-data & apifootball if the result option is not set explicitly!

MethodParams requiredParams optionalfootball-dataapifootball
by_idid: IntegerHTTParty::Response (Hash)Array
allresult (Symbol)
filters (Hash)
ArrayArray
by_competition_and_yearid: Integer
year: String
result (Symbol)
filters (Hash)
ArrayArray
by_competition_and_match_dayid: Integer
match_day: Integer
result (Symbol)
filters (Hash)
ArrayN/A
by_teamid: Integerresult (Symbol)
filters (Hash)
ArrayArray
by_team_and_statusid: Integer
status: String
result (Symbol)
filters (Hash)
N/A
by_team_finishedid: Integerresult (Symbol)
filters (Hash)
ArrayN/A
by_team_scheduledid: Integerresult (Symbol)
filters (Hash)
ArrayN/A
by_playerid: Integerresult (Symbol)
filters (Hash)
ArrayN/A

Examples:

Football::Butler::Matches.by_id(id: 297886)
Football::Butler::Matches.all
Football::Butler::Matches.by_competition_and_year(id: 2002, year: '2019')
Football::Butler::Matches.by_competition_and_match_day(id: 297886, match_day: 1)
Football::Butler::Matches.by_team(id: 18)
Football::Butler::Matches.by_team_and_status(id: 18, status: 'FINISHED')
Football::Butler::Matches.by_team_finished(id: 18)
Football::Butler::Matches.by_team_scheduled(id: 18)
Football::Butler::Matches.by_player(id: 18)

Odds (added in version 2.0.0)

Football::Butler::Odds

Return Values for football-data & apifootball if the result option is not set explicitly!

MethodParams requiredParams optionalfootball-dataapifootball
by_matchid: Integer
from: Date as String (‘2021-05-17’)
to: Date as String (‘2021-05-17’)
(from and to only used (required) in apifootbal.com)
HashHash

Examples:

Football::Butler::Odds.by_match(id: 2002)

Players (added in version 2.0.0)

Football::Butler::Players

Return Values for football-data & apifootball if the result option is not set explicitly!

MethodParams requiredParams optionalfootball-dataapifootball
by_idid: IntegerHashHash
by_namename: Stringresult (Symbol)N/AHash

Examples:

Football::Butler::Players.by_id(id: 2002)

Football::Butler::Players.by_name(name: 'Ronaldo')

Predictions (added in version 2.0.0)

Football::Butler::Predictions

Note: only apifootball_com

Return Values for football-data & apifootball if the result option is not set explicitly!

MethodParams requiredParams optionalfootball-dataapifootball
by_matchid: Integerresult (Symbol)
filters (Hash)
N/AHash

Examples:

Football::Butler::Predictions.by_match(id: 2002)

Scorers (added in version 2.0.0)

Football::Butler::Scorers

alias (apifootball_com): Football::Butler::TopScorers

Return Values for football-data & apifootball if the result option is not set explicitly!

MethodParams requiredParams optionalfootball-dataapifootball
by_competitionid: Integerresult (Symbol)
filters (Hash)
ArrayHash

Examples:

Football::Butler::Scorers.by_competition(id: 2002)

Standings (added in version 1.1.0)

Football::Butler::Standings

Return Values for football-data & apifootball if the result option is not set explicitly!

MethodParams requiredParams optionalfootball-dataapifootball
by_competitionid: Integerresult (Symbol)
filters (Hash)
ArrayArray
home_by_competitionid: Integerresult (Symbol)
filters (Hash)
ArrayN/A
away_by_competitionid: Integerresult (Symbol)
filters (Hash)
ArrayN/A
by_competition_and_yearid: Integer
year: String
result (Symbol)
filters (Hash)
ArrayN/A
Football::Butler::Standings.by_competition(id: 2002)
Football::Butler::Standings.home_by_competition(id: 2002)
Football::Butler::Standings.away_by_competition(id: 2002)
Football::Butler::Standings.by_competition_and_year(id: 2002, year: '2020')

Statistics (added in version 2.0.0)

Football::Butler::Statistics

Note: only apifootball_com

Return Values for football-data & apifootball if the result option is not set explicitly!

MethodParams requiredParams optionalfootball-dataapifootball
by_matchid: Integerresult (Symbol)N/AHash

Examples:

Football::Butler::Statistics.by_match(id: 2002)

Teams

Football::Butler::Teams

Return Values for football-data & apifootball if the result option is not set explicitly!

MethodParams requiredParams optionalfootball-dataapifootball
by_idid: IntegerHTTParty::Response (Hash)Array
by_competitionid: Integerresult (Symbol)
filters (Hash)
ArrayArray
by_competition_and_yearid: Integer
year: String
result (Symbol)
filters (Hash)
ArrayN/A

Examples:

Football::Butler::Teams.by_id(id: 2002)
Football::Butler::Teams.by_competition(id: 2002)
Football::Butler::Teams.by_competition_and_year(id: 2002, year: '2019')

TopScorers

Football::Butler::TopScorers

NOTE: alias of/see Football::Butler::Scorers

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/frontimax/football-butler. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Football Butler project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.