This is a package written as a wrapper for the EVE Swagger Interface (ESI) from the video game Eve Online (https://www.eveonline.com/) in the R programming language which is a leading high level statistical computing language written in the low level C language.
You may read about the R programming language at https://www.r-project.org/ and begin with the internal development environment (IDE) provided by POSIT at https://posit.co/downloads/.
It is important to note to the reader why we chose the R language for a wrapper of ESI. The R language is high level allowing for us to develop scripts at a much more rapid pace. Thus, giving the opportunity to manipulate data from public databases and conduct analyses without the headache of having to think of the machine. Essentially, the goal is to be more human readable and it is easier to make an abstraction of data without having to be explicit with the machine. In our API wrapper, we relied upon the httr2 (https://httr2.r-lib.org/) package to use HTTP protocols to interact and build a library of functions for GET, POST, PUT, DELETE. You may reference how an API works with my notes here https://github.com/kandrsn99/eveR/blob/main/API_EXPLANATION.pdf. It is our hope that anyone using this wrapper learns not only to how to program, but how HTTP protocols work for you.
You may read the following documentation, https://docs.esi.evetech.net/docs/sso/sso_authorization_flow.html, with regards to how a user may be redirected with JSON (javascript object namespace) bearer tokens to give the library scopes allowing the developer to gain private data. Before, the developer obtains scopes for non-public data you must create an application register with the owner, CCP, of the ESI through https://developers.eveonline.com/applications. Please note, that if you are developing on your local machine you should use http://localhost:1011 as the redirect user reference link (URL) if not developing a public web application with a domain name server (DNS).
The reader may reference https://esi.evetech.net/ui/?version=latest#/ for the latest data-end points in the ESI as well as get the related scopes and body models for each function call necessary on a redirect URL.
Also of note is the documentation, https://docs.esi.evetech.net/docs/esi_introduction.html, regarding general practices with make ESI calls through our library such as CCP's rules and versioning. This library will use the latest version of the ESI data end-points.
It must be noted to the reader how an installation is done from the GitHub domain for an R package. You must begin with installing development tools on your local machine in the IDE.
install.packages("devtools")
Then call the devtools library to download through a GitHub user repository.
library(devtools)
Generally speaking, you will install a package from GitHub in the following way.
install_github("DeveloperName/PackageName")
But, for this specific package you will use the subsequent line for the repository.
install_github("kandrsn99/eveRwrapper")
You may reference this article, https://cran.r-project.org/web/packages/githubinstall/vignettes/githubinstall.html, for more detailed ways of installing R packages you may find on the GitHub domain.
Once installed, you may invoke the following to use the functions throughout the package.
library(eveRwrapper)
We shall list some popular functions that call information which may be immediately helpful to a user in Eve Online.
You may want to browse all the functions developed in the package and there are some built in R functions. Typically, there are vignettes which are documents illustrating the package functions.
help(package="eveRwrapper")
This will allow you to pull up any vignettes written for the functions in this package. The next operator you may use is the question mark "?" and the function name to pull up any information regarding passed arguments or return values such as the following GET of the Tranquility server status.
?get_tranquility()
We must begin by creating a client from the register of https://developers.eveonline.com/ where you will name your application and add scopes for a desired application. As soon as this is completed you will get a client id and secret id which you will share with no one to keep the application secure and free from interference. The last thing the register needs is your URL that you will specify that CCP will redirect information. We may see some example of creating variables for your client.
client_id = "my_secret_client_key"
secret_id = "my_top_secret_key"
app_name = "EVE_R"
redirect_machine = "http://localhost:1011"
Subsequently, we will create the client using the following function with substitution.
modify_client(client_id, secret_id, app_name, redirect_machine)
eve_r_client()
You then will call the next function to conduct the initial authentication and get access to the information you want from the ESI through that user.
This function will return the initial bearer token and refresh token. The initial token will last exactly twenty minutes. This initial token will authorize access to specific information for a specific user from the login redirect URL and can be reauthorized with the refresh token sparing us from having to login again.
Finally, we may demonstrate that a function call with your numerical character ID.
get_character_location(character_id)
get_character_market_orders(character_id)
This uses HTTP GET for a character's market orders using R from the ESI. You must have your numerical character ID and a token based on the proper scope from a login redirect URL. The required scopes 'esi-markets.read_character_orders.v1'.
get_character_market_orders_history(character_id, page_value = 1)
This uses HTTP GET for a character's market orders history using R from the ESI. You must have your numerical character ID and a token based on the proper scope from a login redirect URL. Pages value set to default will display a page of values. The required scopes 'esi-markets.read_character_orders.v1'.
get_corporation_market_orders(corporation_id, page_value = 1)
This uses HTTP GET for a corporation's market orders using R from the ESI. You must have your numerical corporation ID and a token based on the proper scope from a login redirect URL. Pages value set to default will display a page of values. The required scopes 'esi-markets.read_corporation_orders.v1' and roles Accountant, Trader.
get_corporation_market_orders_history(corporation_id, page_value = 1)
This uses HTTP GET for a corporation's market orders history using R from the ESI. You must have your numerical corporation ID and a token based on the proper scope from a login redirect URL. The required scopes 'esi-markets.read_corporation_orders.v1' and roles Accountant, Trader.
get_market_groups()
This uses HTTP GET for a market groups using R from the ESI. You must have your numerical character ID and a token based on the proper scope from a login redirect URL. Pages value set to default will display one page of values. The required scopes 'esi-markets.read_corporation_orders.v1' and roles Accountant, Trader.
get_market_history(region_id, item_id)
This uses HTTP GET for a market history using R from the ESI. It will return market values based on the region set and numerical ID of the item.
get_market_orders_region(region_id, order_type = "all", item_id, page_value = 1)
This uses HTTP GET for a market orders using R from the ESI. It will return market orders based on the region set based on the numerical ID of the item. You may choose options all, sell, or buy. The all option is set as default with one page of values.
get_market_orders_type(region_id, page_value = 1)
This uses HTTP GET for a market orders type using R from the ESI. It will return market orders based on the region set. Pages value set to default will display one page of values.
get_market_prices()
This uses HTTP GET for a market prices using R from the ESI. It will return market pricing aggregated by the server.
get_market_structure_orders(structure_id, page_value = 1)
This uses HTTP GET for a market orders per structure using R from the ESI. It will return market orders based on the numerical structure ID with pages value set to default displaying one page of values. The required scopes 'esi-markets.structure_markets.v1'.
get_character_contracts(character_id, page_value = FALSE)
This uses HTTP GET for a character's contracts using R from the ESI. It will return contracts based on the numerical character ID with pages value set to default displaying all contracts. The required scopes 'esi-contracts.read_character_contracts.v1'.
get_character_contracts_bids(character_id, contract_id)
This uses HTTP GET for a character's contract bids using R from the ESI. It will return bids based on the numerical character ID and contract ID. The required scopes 'esi-contracts.read_character_contracts.v1'.
get_character_contracts_items(character_id, contract_id)
This uses HTTP GET for a character's contract items using R from the ESI. It will return items based on the numerical character ID and contract ID. The required scopes 'esi-contracts.read_character_contracts.v1'.
get_corporation_contracts(corporation_id, page_value = FALSE)
This uses HTTP GET for a corporation's contracts using R from the ESI. It will return itmes based on the numerical corporation ID with pages value set to default displaying all contracts. The required scopes 'esi-contracts.read_corporation_contracts.v1'.
get_corporation_contracts_bids(corporation_id, contract_id, page_value = FALSE)
This uses HTTP GET for a corporation's contract bids using R from the ESI. It will return bids based on the numerical corporation ID and contract ID with pages value set to default displaying all contract bids. The required scopes 'esi-contracts.read_corporation_contracts.v1'.
get_corporation_contracts_items(corporation_id, contract_id)
This uses HTTP GET for a corporation's contract items using R from the ESI. It will return items based on the numerical corporation ID and contract ID. The required scopes 'esi-contracts.read_corporation_contracts.v1'.
get_public_contracts(region_id, page_value = FALSE)
This uses HTTP GET for public contracts using R from the ESI. It will return contracts based on numerical region ID with pages value set to default to display all contracts.
get_public_contracts_bids(contract_id, page_value = FALSE)
This uses HTTP GET for a public contract bids using R from the ESI. It will return contracts based on numerical contract ID with pages value set to default to display all contract bids.
get_public_contracts_items <- function(contract_id, page_value = FALSE)
This uses HTTP GET for a public contract items using R from the ESI. It will return contracts based on numerical contract ID with pages value set to default to display all contract items.
get_character_colony(character_id, planet_id)
This uses HTTP GET for a character's colonies using R from the ESI. You must have your numerical character ID, planet ID, and a token based on the proper scope from a login redirect URL. The required scopes 'esi-planets.manage_planets.v1'.
get_character_planets(character_id)
This uses HTTP GET for a character planets using R from the ESI. You must have your numerical character ID and a token based on the proper scope from a login redirect URL. The required scopes 'esi-planets.manage_planets.v1'.
get_corporation_custom_offices(corporation_id, page_value = FALSE)
This uses HTTP GET for a corporation custom offices using R from the ESI. You must have your numerical corporation ID and a token based on the proper scope from a login redirect URL. Pages value set to default will display all custom offices. The required scopes 'esi-planets.read_customs_offices.v1' and the role of 'Director'.
get_universe_schematics(schematic_id)
This uses HTTP GET for a PI schematic using R from the ESI. You must have the schematic ID.
get_character_industry_jobs(character_id, job_completion = TRUE)
This uses HTTP GET for a character's industry jobs using R from the ESI. You must have your numerical character ID and a token based on the proper scope from a login redirect URL. Job completion true or false will change displayed information slightly. The required scopes 'esi-industry.read_character_jobs.v1'.
get_character_mining(character_id, page_value = FALSE)
This uses HTTP GET for a character's mined materials using R from the ESI. You must have your numerical character ID and a token based on the proper scope from a login redirect URL. Page value set to default will display all mined materials. The required scopes 'esi-industry.read_character_mining.v1'.
get_corporation_industry_jobs(corporation_id, job_completion = TRUE, page_value = 1)
This uses HTTP GET for a corporation's industry jobs using R from the ESI. You must have your numerical corrporation ID and a token based on the proper scope from a login redirect URL. Page value set to default will display one page of values. The required scopes 'esi-industry.read_corporation_jobs.v1' and the role of 'Factory_Manager'.
get_corporation_mining_extractions(corporation_id, page_value = FALSE)
This uses HTTP GET for a corporation's mining extractions using R from the ESI. You must have your numerical corporation ID and a token based on the proper scope from a login redirect URL. Page value set to default will display all extractions. The required scopes 'esi-industry.read_corporation_mining.v1' and the role of 'Station_Manager'.
get_corporation_mining_observers(corporation_id, page_value = 1)
This uses HTTP GET for a corporation's mining observers using R from the ESI. You must have your numerical corporation ID and a token based on the proper scope from a login redirect URL. Page value set to default will display one page of observers. The required scopes 'esi-industry.read_corporation_mining.v1' and the role of 'Accountant'.
get_corporation_mining_observers_id(corporation_id, observer_id, page_value = 1)
This uses HTTP GET for a corporation's mining observer's ID using R from the ESI. You must have your numerical corporation ID and a token based on the proper scope from a login redirect URL. Page value set to default will display one page of observers. The required scopes 'esi-industry.read_corporation_mining.v1' and the role of 'Accountant'.
get_industry_facilities()
This uses HTTP GET for industrial facilities using R from the ESI.
get_industry_systems()
This uses HTTP GET for industrial systems using R from the ESI.
post_universe_ids(name_list, language_value = "en-us")
This uses HTTP POST for IDs of the Eve Universe using R from the ESI. It takes a list of names to give the universe numerical ID.
post_universe_names(id_list)
This uses HTTP POST for names of the Eve Universe using R from the ESI. It takes a list of numerical IDs to give the universe name.