release 0.1 - read the docs · igdb-api documentation, release 0.1.0 available postfixes: •eq:...
TRANSCRIPT
igdb-api DocumentationRelease 0.1.0
easy change
Oct 26, 2017
Contents
1 igdb-api 31.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Installation 52.1 From sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3 Concepts 73.1 Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.3 Text search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83.4 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4 Usage and Examples 94.1 Games . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.2 Companies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.3 Franchises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.4 Genres . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.5 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.6 People . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.7 Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.8 Player Perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.9 Pulses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.10 Series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.11 Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.12 Examples with filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5 Contributing 155.1 Types of Contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155.2 Get Started! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165.3 Pull Request Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6 History 196.1 0.1.0 (2016-07-30) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
i
ii
igdb-api Documentation, Release 0.1.0
Contents:
Contents 1
igdb-api Documentation, Release 0.1.0
2 Contents
CHAPTER 1
igdb-api
Unofficial python api for igdb
Features
• Requests json objects from igdb:
• Games
• Companies
• Franchises
• Genres
• Keywords
• People
• Platforms
• Player Perspectives
• Pulses
• Series
• Themes
For more information please visit https://www.igdb.com/api
3
igdb-api Documentation, Release 0.1.0
4 Chapter 1. igdb-api
CHAPTER 2
Installation
From sources
The sources for igdb-api can be downloaded from the Github repo.
You can either clone the public repository:
$ git clone git://github.com/nuxlic/igdb-api
Or download the tarball:
$ curl -OL https://github.com/nuxlic/igdb-api/tarball/master
Once you have a copy of the source, you can install it with:
$ python setup.py install
5
igdb-api Documentation, Release 0.1.0
6 Chapter 2. Installation
CHAPTER 3
Concepts
Extract of https://market.mashape.com/igdbcom/internet-game-database/overview
Fields
Fields are properties of an entity. For example, a Game field would be rating or release_dates. Some fields haveproperties of their own, for example, the esrb field has the property synopsis. Fields are requested in a commaseparated list. For example, to get some information for some Games, Genres, Themes or anything else, you couldrequest it like this:
fields = 'name,release_dates,esrb.synopsis,rating'
Note the synopsis property of esrb can be accessed directly with a dot.
The timestamps/dates is always measured in nanoseconds since unix epoch.
A full list of fields can be obtained by passing a * as a field.
Filters
Filters are used to sift through results to get what you want. You can exclude and include results based on theirproperties. For example you could remove all Games where the rating was below 80 (filter[rating][gte]=80).
>> from igdb import Filter>> from igdb.operators import GTE, GT>> filter = Filter(field='rating', operator=GTE, value=80)>> filter = Filter(field='release_dates.date', operator=operators.GT, value='2016-02-→˓21')
The filter itself comprises of 2 parts; The field and the postfix. Fields are described in the section on the left, postfixesare described below.
7
igdb-api Documentation, Release 0.1.0
Available Postfixes:
• eq: Exact match equal.
• gt: Greater than works only on numbers.
• gte: Greater than or equal to works only on numbers.
• lt: Less than works only on numbers.
• lte: Less than or equal to works only on numbers.
• prefix: Prefix of a value only works on strings.
• exists: The value is not null.
Text search
search: This parameter is not like other filters. It is an independant parameter that performs a full text search.
Ordering
Ordering (Sorting) is used to order results by a specific field. You can order results like this:
order = 'release_dates.date:desc'
Notice the appended :desc which could also be :asc if required.
8 Chapter 3. Concepts
CHAPTER 4
Usage and Examples
First you need an api key. Please visit https://market.mashape.com/igdbcom/internet-game-database to get it.
To use igdb-api:
>> from igdb.requester import Requester>> api_key = 'sk2aWPgu1SmshudWmsdsdsfsgfsdfsH4gb9Hp1pWaUEjsnSl1Wo4SIsYri'>> req = Requester(api_key)
Games
>> req.get_games(fields='*', limit=10, offset=0, order='release_dates.date:desc',→˓search='Crysis')[1]>> {'aggregated_rating': 73.55555555555556,
'category': 0,'collection': 36,'cover': {'cloudinary_id': 'ql2wkpjr0wr8s42qnd9o',
'height': 1964,'width': 1530},
'created_at': 1345474459983,'developers': [122, 158],'esrb': {'rating': 6,
'synopsis': 'This is a first-person shooter in which players assume ''the role of a soldier who battles an evil corporation ''and must defend Earth from alien invasion. Players use ''handguns, machine guns, rocket launchers, and ''futuristic weapons to kill Ceph aliens and human ''soldiers. Players can also engage in close-up '"hand-to-hand combat: slicing enemies' throats, breaking "'their necks. The frenetic combat includes realistic ''gunfire, screams of pain, and frequent explosions. ''Characters emit large splashes of blood when shot or ''stabbed; bloodstains can be seen on the ground. The '
9
igdb-api Documentation, Release 0.1.0
'words “f**k” and “sh*t” can be heard in the dialogue.'},'game_engines': [25],'genres': [5, 31],'id': 1268,'keywords': [132, 453, 466, 1025, 1917, 2210],'name': 'Crysis 3','pegi': {'rating': 4,
'synopsis': 'The content of this game is suitable for persons aged ''16 years and over only.\n''It contains: Realistic looking violence - - Strong ''language\n''This game allows the player to interact with other ''players ONLINE'},
'publishers': [1],'rating': 78.43730001427213,'rating_count': 42,'release_dates': [{'category': 0, 'date': 1361232000000, 'platform': 6},
{'category': 0, 'date': 1361232000000, 'platform': 12},{'category': 0, 'date': 1361232000000, 'platform': 9}],
'screenshots': [{'cloudinary_id': 'w4wtnrsi7adlgqdrcquh','height': 360,'width': 640},
{'cloudinary_id': 'vdc5hsctsutblkjbdhux','height': 1080,'width': 1920},
{'cloudinary_id': 'hb9udiacxii5dezi2jsa','height': 360,'width': 640},
{'cloudinary_id': 'ldrntvvj3rn6snpke6bd','height': 360,'width': 640},
{'cloudinary_id': 'ria78seajdtfopxhlkjr','height': 360,'width': 640}],
'slug': 'crysis-3','storyline': 'Return to the fight as Prophet, the Nanosuit soldier on a quest '
'to rediscover his humanity. Adapt on the fly with the stealth ''and armor abilities of your unique Nanosuit as you battle ''through the seven wonders of New York’s Liberty Dome. Unleash ''the firepower of your all-new, Predator bow and alien weaponry ''to hunt both human and alien enemies.',
'summary': 'The award-winning developer Crytek is back with Crysis 3, the ''first blockbuster shooter of 2013! Crysis 3 is the ultimate ''sandbox shooter, realized in the stunning visuals only Crytek and ''the latest version of CryENGINE can deliver. Available now on ''Xbox 360, PlayStation 3, and PC.',
'themes': [23, 18],'updated_at': 1470897659310,'url': 'https://www.igdb.com/games/crysis-3','videos': [{'name': 'The Hunt Is On Trailer', 'video_id': 'lAOaKmuavsQ'}]}
Companies
>> req.get_companies(fields='*', limit=10, offset=0)[1]>> {'change_date_category': 7,
10 Chapter 4. Usage and Examples
igdb-api Documentation, Release 0.1.0
'created_at': 1466618242964,'developed': [13046],'id': 10172,'name': 'Source the Software House','slug': 'source-the-software-house','start_date_category': 7,'updated_at': 1466630360982,'url': 'https://www.igdb.com/companies/source-the-software-house'}
Franchises
>> req.get_franchises(fields='*')[1]>> {'created_at': 1470735085952,
'games': [22388, 22389, 22390],'id': 844,'name': 'Death Note','slug': 'death-note','updated_at': 1470735085952,'url': 'https://www.igdb.com/franchises/death-note'}
Genres
>> req.get_genres(fields='*', limit=40)[1]>> {'created_at': 1341431954666,
'games': [1031,22381,22383,22386,22387,18148,18981,22403,22409,22414,22417],
'id': 32,'name': 'Indie','slug': 'indie','updated_at': 1341431954666,'url': 'https://www.igdb.com/genres/indie'}
Keywords
>> req.get_keywords(fields='*', limit=50, offset=0)[1]>> {'created_at': 1401296058552,
'games': [4838, 7060, 8862],'id': 1081,'name': 'masked wrestling','slug': 'masked-wrestling',
4.3. Franchises 11
igdb-api Documentation, Release 0.1.0
'updated_at': 1401296058552,'url': 'https://www.igdb.com/categories/masked-wrestling'}
People
>> req.get_people(fields='*')>> {'created_at': 1412519219083,
'games': [8223, 3025],'gender': 0,'id': 32377,'name': 'Kristianne Bilodeau','slug': 'kristianne-bilodeau','updated_at': 1467293030099,'url': 'https://www.igdb.com/people/kristianne-bilodeau'}
Platforms
>> req.get_platforms(fields='*', limit=50, offset=0)[1]>> {'alternative_name': 'Nintendo Super Disc',
'created_at': 1468482761733,'id': 131,'name': 'Nintendo PlayStation','slug': 'nintendo-playstation','updated_at': 1468574267550,'url': 'https://www.igdb.com/platforms/nintendo-playstation','versions': [{'name': 'Initial version',
'slug': 'initial-version','url': 'https://www.igdb.com/platforms/nintendo-playstation/version/
→˓initial-version'}]}
Player Perspectives
>> req.get_player_perspectives(fields='*')[1]>> {'created_at': 1413209511809,
'games': [9076,2629,7698,8597,8662,8612,18981],
'id': 6,'name': 'Aural','slug': 'aural','updated_at': 1413209511809,'url': 'https://www.igdb.com/player_perspectives/aural'}
12 Chapter 4. Usage and Examples
igdb-api Documentation, Release 0.1.0
Pulses
>> req.get_pulses(fields='*')[1]>> {'author': 'MaGuishi',
'category': 1,'id': 6711,'image': 'http://b.thumbs.redditmedia.com/L-KfQC4sT0Y5AuYMUhn3w_
→˓8p0sfnjMW2eZrhsleA5Lk.jpg','published_at': 1456151397000,'title': 'Los Santos@Minecraft','uid': '4711ju','url': '/r/gaming/comments/4711ju/los_santosminecraft/'}
Series
>> req.get_series(fields='*')[1]>> {'created_at': 1422487135147,
'games': [8817],'id': 1192,'name': 'Smugglers','slug': 'smugglers','updated_at': 1422487135147,'url': 'https://www.igdb.com/collections/smugglers'}
Themes
>> req.get_themes(fields='*', limit=40)[1]>> {'created_at': 1356889401895,
'games': [1712,8567,22408,19930,22417],
'id': 40,'name': 'Party','slug': 'party','updated_at': 1356889401895,'url': 'https://www.igdb.com/themes/party'}
Examples with filters
>> from igdb import Filter>> from igdb.operators import EQ>> filter_name = Filter(field='name', operator=EQ, value='Crysis 3')>> req.get_games(fields='*', limit=10, offset=0, order='release_dates.date:desc',→˓filters=[filter_name])
4.9. Pulses 13
igdb-api Documentation, Release 0.1.0
14 Chapter 4. Usage and Examples
CHAPTER 5
Contributing
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Types of Contributions
Report Bugs
Report bugs at https://github.com/nuxlic/igdb-api/issues.
If you are reporting a bug, please include:
• Your operating system name and version.
• Any details about your local setup that might be helpful in troubleshooting.
• Detailed steps to reproduce the bug.
Fix Bugs
Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wantsto implement it.
Implement Features
Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open towhoever wants to implement it.
15
igdb-api Documentation, Release 0.1.0
Write Documentation
igdb-api could always use more documentation, whether as part of the official igdb-api docs, in docstrings, or even onthe web in blog posts, articles, and such.
Submit Feedback
The best way to send feedback is to file an issue at https://github.com/nuxlic/igdb-api/issues.
If you are proposing a feature:
• Explain in detail how it would work.
• Keep the scope as narrow as possible, to make it easier to implement.
• Remember that this is a volunteer-driven project, and that contributions are welcome :)
Get Started!
Ready to contribute? Here’s how to set up igdb-api for local development.
1. Fork the igdb-api repo on GitHub.
2. Clone your fork locally:
$ git clone [email protected]:your_name_here/igdb-api.git
3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set upyour fork for local development:
$ mkvirtualenv igdb-api$ cd igdb-api/$ python setup.py develop
4. Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing otherPython versions with tox:
$ flake8 igdb_api tests$ python setup.py test or py.test$ tox
To get flake8 and tox, just pip install them into your virtualenv.
6. Commit your changes and push your branch to GitHub:
$ git add .$ git commit -m "Your detailed description of your changes."$ git push origin name-of-your-bugfix-or-feature
7. Submit a pull request through the GitHub website.
16 Chapter 5. Contributing
igdb-api Documentation, Release 0.1.0
Pull Request Guidelines
Before you submit a pull request, check that it meets these guidelines:
1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a functionwith a docstring, and add the feature to the list in README.rst.
3. The pull request should work for Python 3.3, 3.4 and 3.5, and for PyPy.
5.3. Pull Request Guidelines 17
igdb-api Documentation, Release 0.1.0
18 Chapter 5. Contributing
CHAPTER 6
History
0.1.0 (2016-07-30)
• First release.
19