Dear players,

first off, a couple of words about this post: We have been monitoring feedback in the communities about how 3rd party tools interact with OGame. In order to work together on some of these issues we want to try out this new type of "Dev Post". To accommodate all language communities these posts will be made in the Origin Board and in english only. Feel free to direct any potentially interested players / developers to this post.

Now, for the good stuff:

As you have probably heard, with OGame 6.0 changes to the display of Combat Reports (CR) are being made. This has caused concerns about different 3rd party tools breaking because of these changes. To address these concerns and for a more stable solution, we have fleshed out the following:

We wish to offer players the possibility to share combat reports with 3rd party tools in a more simplified and safe manner.

For this we are currently planning a new API that will allow 3rd party developers to directly request combat reports from our servers. In an upcoming snapshot of version 6.0 players will find a new button on their combat reports that allows them to copy a Combat ID to their clipboard (CR_ID).

Using this CR_ID and an application key (API_KEY) issued to 3rd party developers by OGame, tools will be able to directly request the combat information from our server in a machine readable format for storage and processing on their own servers. We *will* be monitoring requests to the API *very* closely.

Please note: The player himself stays in control of which CR_IDs is shared, it will not be possible to retrieve CRs without the ID the player provides.

Our reasonings for this move are the following:

• Combat Report websites will have the opportunity to easily get the information they need without the user having to copy & paste whole combat reports from in game and the site having to parse HTML code.
  
  
• Combat reports retrieved this way can not be tampered with by the player issuing the CR_ID to a 3rd party developer.
  
  
• The data is easily retrieved and decoded by most programming languages.
  
  
• The data is independent of localization, allowing for more cross- community tools.
  
  
• Different tools / websites will be able to process the data in different ways, opening up new possibilities for them to present the information they chose to show.
  
  
• No more parsing of complex HTML code required.
  

We are currently still fleshing out the format of the key and the data to be returned by the API, as well as technical formalities that need to be taken care of before we open up this API to the communities.

Additionally, we are working on procedures for requesting API_KEYs from OGame. Most likely, Test Servers will have a global API_KEY for testing purpose, live server can only be accessed with a personalized API_KEY (per tool/website/3rd party developer).

Depending on the acceptance of "API verified" combat reports, we may extend this new API to other pieces of game information in the future, for example alliance or per-user information.

Attached is a mock screen shot of how this associated ID could look like:


Please keep discussions in this thread technical in nature.

For other feedback please use the separate discussion thread available here: New API for retrieval of combat reports

Raid safely,

DevLaTron

Hello again,

thank you for all your feedback on the API! We want to answer some questions that we collected since the release of the initial post.

Question: "Will the API allow access to other information like profit/losses, mine production, IPM attacks, espionage reports, fleets,
scores, statistics?"

We have to take great care about what information will be provided and how to ensure that game balance and different play styles are not disrupted, but are open to suggestions. For our first round it's safe to assume that most things you can find in a normal combat report will also be available via an API call.

Additionally we need to provide players with methods to revoke and modify access to their information. We have an idea how to resolve this and we will disclose this once the API will be closer to release on a test server.

While sharing a combat or espionage report is a one way situation (Once shared it's public), mining production or planet positions are things that fluctuate and need to be handled differently to make sense in an API, as we can't simply "snapshot" the current production every time a player wants to share it.

Last, there is static content and statistics that we can provide, which is currently done via the existing API which will need to be handled differently again.

In general, if you can provide us with an idea and what information you would need to make it happen, it would help us in the decision making process on our side. If you already have a site/application, feel free to point out where you are having issues retrieving data.

Question: "I want to build an application that does XYZ, is that okay?"

This isn't something we as developers (a.k.a. programmers) can help you with. But here are some bits of information to help you out:

First, make sure your idea does not conflict with our Terms and Rules. You can find them in game and on the boards of your corresponding community.

You will also want to check the boards for procedures for getting your application, website or service approved by Gameforge on a case by case basis. The origin board has a dedicated sub-forum for this as well.

Finally, please keep in mind that this API will not be suited for direct access from desktop tools or mobile apps. You will need to provide a proxy server that caches and stores the information you query from the API. One reason for this is that we need to make sure you keep your access key private and to restrict access to the API as needed. We will provide more information on how this will work as we progress on the API.

Question "What data format will the API use?"

As you may know, we already provide an API for statistical purposes which returns XML and also provide some information in HTTP headers to support tool developers. This works well because XML is human readable and easily integrated into browser side add-ons, which is usually rendered on the player computer. The "old" API will remain untouched, and most likely the new API will return JSON. Further down the road we will probably discuss also making the XML information available in JSON.

We hope that members of the community will step forward and provide others with (Hint: open source) libraries that connect to our API and take care of the communication between application and API.

Question: "Will the API be read only? Are there any plans to add write access?"

At this time, there are no plans for write access, the reason being that it would create serious security and gameplay issues. Again, if you find you have the need this, please come forward and explain to us why and what you need so are aware of this for the future.

Raid safely,

DevLaTron

Hello again,

it has been a while since our last post, mostly because we are busy squatting all the bugs in 6.0. Today, we are happy to announce that with Beta1 of 6.0 our new API will be going live on the test servers. In "v1" of this API you will be able to request combat reports directly from our servers via an easy to use API.

Please remember that this version of the API is still work in progress, yet we wanted to provide you with a working version as soon as possible. Keep in mind that things may change until the final release of 6.0, with which you can expect the final 1.0 release of the API.

For our initial testing we will provide select people with an API key, which is required to access the new API. To request one, please post in the appropriate thread: --> Applications for API Keys 6.0.0-beta1 <--- with a short description of what your project looks like. We will then contact you personally via PM to collect the information required for issuing your private API key. Please keep the following Information at hand once we contact you:

- A short description of the tool you want to create or a link to an existing tool you already have / want to update.
- A short description of your developer / programming experience
- The scope of your project: Personal, Alliance, Community or International.
- Valid EMail address.
- The IP from which your tool will connect to our servers. (Limited to 1 during testing).
- Are you willing to "open source" some of your source code for others to benefit from? (Example: Providing a library for a specific programming language)
- Are you willing to help with extended testing? This may require you to provide us with more contact information. (IRC contact and approximate online availability).

After we have checked your information, you will receive your personal API key for testing via EMail.

Using this API key you will be able to issue requests to the API. Below is an example to retrieve combat reports in PHP. The code below has been shortened down for explanation purposes only, you must add Logging and Error handling as well as caching and timing code yourself! Please note that you should store the CR information on your own server and not request it multiple times!

Only combat reports created *after* beta1 are available, older CR_IDs have been deleted. Also, combat reports are only available from servers that have beta1 or later deployed. CR-Keys can be found on the top of detailed combat reports. Instability and bugs are to be expected.





RESULT_CODE currently may be any of the following:

OK = 1000;
INVALID_VERSION = 4000;
INVALID_API_KEY = 4001;
INVALID_API_KEY_EXPIRED = 4002;
INVALID_API_PERMISSION = 4003;
INVALID_PATH = 4004;
INTERNAL_ERROR = 5000;
INVALID_CR_ID = 6000;
INVALID_SR_ID = 6001;
INVALID_RR_ID = 6002;
INVALID_MR_ID = 6003;


If your RESULT_CODE is "OK", RESULT_DATA will contain contain a JSON string with this layout:

1) Generic:




2 + 3) attackers and defenders, for each entry (up to the amount found in "generic"):




4) rounds, for each combat round with detailed information (Shots fired, ships destroyed, etc).
Currently not implemented ,we hope to be able to provide you with detailed round information in beta2.


This should be enough information to get Tool developers started on their Combat Report Parsers, Highscore Lists, "Largest Fight ever"- Page or whatever comes to your mind.

Please direct all bugs / Feedback to the appropriate Threads on the Origin Forums, remember to provide the CR-KEY that created the bug/error.

Raid safely!


Edited: Added missing loot and debris fields in generic section.
Edited: Added missing timestamp and datetime in generic section.