{"id":22180516,"url":"https://github.com/s1m0n38/soccerapi","last_synced_at":"2025-04-06T23:16:42.569Z","repository":{"id":54314524,"uuid":"232615041","full_name":"S1M0N38/soccerapi","owner":"S1M0N38","description":"soccerapi, an unambitious soccer odds scraper ⚽️","archived":false,"fork":false,"pushed_at":"2022-12-08T08:48:45.000Z","size":214,"stargazers_count":167,"open_issues_count":18,"forks_count":36,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-03-30T22:11:40.529Z","etag":null,"topics":["888sport","api","bet","bet365","betting","bookmakers","football","odds","soccer","soccer-api","unibet"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/S1M0N38.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-08T17:07:31.000Z","updated_at":"2025-03-27T14:02:29.000Z","dependencies_parsed_at":"2023-01-24T20:15:20.582Z","dependency_job_id":null,"html_url":"https://github.com/S1M0N38/soccerapi","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/S1M0N38%2Fsoccerapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/S1M0N38%2Fsoccerapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/S1M0N38%2Fsoccerapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/S1M0N38%2Fsoccerapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/S1M0N38","download_url":"https://codeload.github.com/S1M0N38/soccerapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247563935,"owners_count":20958971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["888sport","api","bet","bet365","betting","bookmakers","football","odds","soccer","soccer-api","unibet"],"created_at":"2024-12-02T09:18:29.991Z","updated_at":"2025-04-06T23:16:42.539Z","avatar_url":"https://github.com/S1M0N38.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e :warning:\n\u003e At the moment this project is not actively developed. \n\u003e Due to bookmakers' sites update some functionality may be broken.\n\u003e :warning:\n\n# soccerapi\n\n[![PyPI version](https://badge.fury.io/py/soccerapi.svg)](https://badge.fury.io/py/soccerapi)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nSoccerapi (Application Programming Interface) is a simple wrapper build on top\nof some bookmakers (888sport, bet365 and Unibet) in order to get data about\nsoccer (aka football) odds using python commands.\n\n## ⚽️ The goal\n\nThe goal of the project is to provide an enjoyable way to get odds data for\ndifferent soccer leagues. If you want to get these types of data you usually\nhave to build a program by yourself (and from scratch) being able to scrape the\nbetting site or to use some kind of paid API. Soccer API try to address this problem.\n\n## 💡 The philosophy\n\nKeep it simple. Simple API, simple http requests, few dependencies. In the past\nwe tried to build some heavy framework, able to scrape dinamic sites (using\nselenium, handling complex JavaScript): was an *unmaintainable nightmare*.\n\n## 📘 The documentation\n\nThe following section contain all the useful information to use this API at\nits best. Read it carefully.\n\n### Installation\n\nUse your favorite python package manager (like *pip*, *pipenv*, *poetry*). For\nexample if you use *pip* type in your terminal:\n\n```bash\npip install --upgrade soccerapi\n```\n\nIt's important to keep soccerapi updated to the last version because bookmakers\nsometimes change their website so soccerapi could break. We the last version on\nthe master branch we try to keep up.\n\n------------------------------------------------------------------------------\n\nAlternatively, if you want a kind of testing/developing setup, you can install\nsoccerapi directly from source code by first cloning the repository from\nGitHub and then install dev dependencies\n([poetry](https://python-poetry.org/) is required)\n\n```bash\ngit clone https://github.com/S1M0N38/soccerapi.git\ncd soccerapi\npoetry install\n```\n\nFinally activate the environment\n\n```bash\npoetry shell\n```\n\n------------------------------------------------------------------------------\n\nIn order to obtain data from [Bet365](https://www.bet365.com/) you need to \nrun a docker which posts on a local server a needed header to make requests\nto the Bet365 api. The docker run separeately from the api since it is written\nin JavaScript and it runs a *chromedirver* to run JavaScript and acquire the\nheader.\n\nCheckout [soccerapi-server](https://github.com/S1M0N38/soccerapi-server) to \ninstall the docker and run it.\n\n### Usage\n\nImport the *soccerapi* bookmaker, define the *api* variable and request\n*odds*.\n\n```python\nfrom soccerapi.api import Api888Sport\n# from soccerapi.api import ApiUnibet\n# from soccerapi.api import ApiBet365\n\napi = Api888Sport()\nurl = 'https://www.888sport.com/#/filter/football/italy/serie_a'\nodds = api.odds(url)\n\nprint(odds)\n```\n\n```python\n[\n  {\n    'time': '2020-01-12T19:45:00Z'\n    'home_team': 'Roma',\n    'away_team': 'Juventus',\n    'both_teams_to_score': {'no': 2380, 'yes': 1560},\n    'double_chance': {'12': 1320, '1X': 1710, '2X': 1360},\n    'full_time_resut': {'1': 3200, '2': 2160, 'X': 3450},\n  },\n\n  ...\n\n  {\n    'time': '2020-01-13T19:45:00Z'\n    'home_team': 'Parma',\n    'away_team': 'Lecce',\n    'both_teams_to_score': {'no': 2280, 'yes': 1600},\n    'double_chance': {'12': 1270, '1X': 1270, '2X': 1960},\n    'full_time_resut': {'1': 1850, '2': 3850, 'X': 3800},\n  }\n]\n```\n\nThe *odds()* method return a list of next events of the request competition\n(in the example: the url points to *italy-serie_a*)\n\nTo get a dict of valid urls that you can pass to `odds()` use the method\n`competitions()`.\n\n```python\nodds = api.competitions()\n\nprint(odds)\n```\n\n```python\n{\n\n'Algeria': {\n    'Ligue 1': 'https://www.888sport.com/#/filter/football/algeria/ligue_1',\n    'Ligue 1 U21': 'https://www.888sport.com/#/filter/football/algeria/ligue_1_u21'\n},\n\n'Argentina': {\n    'Primera D Metropolitana': 'https://www.888sport.com/#/filter/football/argentina/primera_d_metropolitana'\n},\n\n'Australia': {\n    'A-League': 'https://www.888sport.com/#/filter/football/australia/a-league',\n    'W-League (W)': 'https://www.888sport.com/#/filter/football/australia/w-league__w_'\n},\n\n...\n\n}\n```\n\nThis python dict is dynamically generated every time the `competitions()` method\nis run.  This method crawls the bookmaker site looking for the available\ncompetitions and extract the url for every competitions offered by the bookmaker.\n\nFor some bookmakers (Bet365) many http requests are perform by `competitions()`,\nso there is the risk of receiving an IP ban. Use this method wisely\n(e.g. store the competitions in a json file and update them only when necessary).\n\nThe main reasons we introduced the `competitions()` method is due to the fact that \nsome bookmakers (Bet365) change the url for a competitions over time in order to \ncontrast bot scraping, so do not trust on a static list of urls for every bookmaker.\n\n### Country restriction\n\nThe regulation of online gambling varies from country to country. There are\ndifferent versions of the bookmaker site depending on the provenience of your\nhttp request. Moreover, most bookmakers implement some kind of VPN detection\nwhich block VPN-http requests. Due to this constrains it's difficult to test\nsoccerapi for worldwide usability. In the following are reported some results\nof the availability of bookmaker in different countries.\n\n|            | bet365 | 888sport / unibet |\n|----------- | :----: | :---------------: |\n|accessible  | :it: :brazil:  | :us: :canada: :australia: :brazil: :switzerland: :it: :de: :denmark: :es: :finland: :jp: :netherlands: :norway: :sweden: :ireland: :india: :singapore: :hong_kong: :new_zealand: :mexico: :romania:|\n|inaccessible|        | :fr: :uk:         |\n\n### Contributing\n\nIf you like to contribute to the project read\n[CONTRIBUTING.md](https://github.com/S1M0N38/soccerapi/blob/master/CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs1m0n38%2Fsoccerapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fs1m0n38%2Fsoccerapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs1m0n38%2Fsoccerapi/lists"}