This is one of the more difficult API calls to use and understand but with a bit of study, you should be able to use it competently. As you are aware, Everygamegoing contains thousands and thousands of reviews from different magazines (You can use the call to getAllMagazines to see them all). What this command does is ask some of the following questions for you:

  1. Which games did Amstrad Action think had the best graphics?
  2. What were Electron User's highest rated games of all time?
  3. Which items did Personal Computer News think made the best use of the machine?

It does this by using the following structure:[mag_key]/[mag_value]/[mag_element_key]/[limit]/

[mag_key], [mag_value] and [mag_element_key] are all mandatory parameters and no results will be returned without both of them being specified correctly.

[limit] is an optional parameter. If not given, a limit of 1 will be used.

Stepping through the parameters in the call:

[mag_key] must be a string of 'mag_id' or 'mag_name'.

[mag_value] must be the appropriate value corrresponding to the [mag_key] specified.

If you were interested in asking the question "Which games did Amstrad Action think had the best graphics?" you could therefore compose the call as:

or, you could use the magazine's name, as follows:

In the above examples, the [mag_element_key] used is the text string 'Graphics'. However, different magazines featured different scoring systems, hence you need to know the [mag_element_key] specific to the magazine that you are querying in order to get the results that you want.

This is where the complexity in using the call is to be found, as the only way to obtain the [mag_element_key] parameter you need is to choose it from those returned by a call to getAllMagElementKeysForReviewsInMag with the same [mag_key] and [mag_value] parameters.

If we stick with Amstrad Action as the magazine, and now issue this other API call:

we receive back the following options for [mag_element_key]:

  1. Atmosphere
  2. Challenge
  3. Farting Sonics
  4. Grab Factor
  5. Graphics
  6. Interaction
  7. Overall
  8. Puke Factor
  9. Sonics
  10. Sound
  11. Staying Power

So, substituting 'Interaction' for 'Graphics' would be to pose the alternative question "Which games did Amstrad Action think had the best interaction?"

When you compose a valid call, you will receive a response similar to the following:

			"show_title":"Burnin' Rubber",
			"machine_type_group_name":"Amstrad CPC 464+\/GX4000",
			"show_title":"Knight Force",
			"machine_type_group_name":"Amstrad CPC464",

The fields returned are all self-explanatory but a table explaining them is given below.

Key Human-readable Explanation Value Data Type Value Example
mag_element_value Mag Element Value String 100%
show_title Show Title String Burnin' Rubber
machine_type_group_name Machine Type Group String Amstrad CPC 464+/GX4000
publisher_info Publisher String Ocean
item_id Item ID String 51294
machine_type_group_default_folder Machine Type Group Default Folder String c64
publisher_folder Publisher Folder String ocean
format_folder Format Folder String rom_carts
item_title Item Title/Filename String Burnin_Rubber
mag_article_id Mag Article ID String 26677

You can see an illustration of how Everygamegoing uses this call on this page.