{"id":15667615,"url":"https://github.com/bentheburrito/planetside_api","last_synced_at":"2025-08-23T19:06:32.353Z","repository":{"id":43872415,"uuid":"252813287","full_name":"Bentheburrito/planetside_api","owner":"Bentheburrito","description":"An Elixir library for interacting with Daybreak Games' Planetside 2 API","archived":false,"fork":false,"pushed_at":"2023-07-22T17:28:22.000Z","size":142,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-01T06:07:35.002Z","etag":null,"topics":["elixir","planetside2","rest-api"],"latest_commit_sha":null,"homepage":"https://hex.pm/packages/planetside_api","language":"Elixir","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/Bentheburrito.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-03T18:46:02.000Z","updated_at":"2023-06-03T20:45:32.000Z","dependencies_parsed_at":"2024-10-03T14:04:38.504Z","dependency_job_id":"e45552e3-6355-421d-82a7-a73e2b0ddb1c","html_url":"https://github.com/Bentheburrito/planetside_api","commit_stats":{"total_commits":37,"total_committers":1,"mean_commits":37.0,"dds":0.0,"last_synced_commit":"fd680619cf910026aeffbe30ad37bc192f601ed0"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bentheburrito%2Fplanetside_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bentheburrito%2Fplanetside_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bentheburrito%2Fplanetside_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bentheburrito%2Fplanetside_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bentheburrito","download_url":"https://codeload.github.com/Bentheburrito/planetside_api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252757867,"owners_count":21799742,"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":["elixir","planetside2","rest-api"],"created_at":"2024-10-03T14:04:30.663Z","updated_at":"2025-05-06T19:47:36.005Z","avatar_url":"https://github.com/Bentheburrito.png","language":"Elixir","readme":"# Planetside 2 API Wrapper\n\nA library that provides clean PS2 Census query creation\nand Event Stream management for Elixir developers.\n\nView the full documentation [on hexdocs.pm](https://hexdocs.pm/planetside_api/PS2.API.html#content)\n\n## Installation\n\nAdd `planetside_api` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:planetside_api, \"~\u003e 0.3.4\"}\n  ]\nend\n```\n\n## Census API Queries\n\nThis wrapper provides several data structures and functions\nthat make creating readable Census API queries easy. The\nstructs, `PS2.API.{Query, Join, Tree}`, can be manipulated\nand added to via the functions from `PS2.API.QueryBuilder`.\n\n`Query` is a struct representation of a Census query that is\nencoded into its url form when passed to `PS2.API.query/1`\nor `PS2.API.encode/1`. A `Query` can contain many `Join`s and\na `Tree`.\n\n### Example query with a join and tree\n\n```elixir\n# alias struct modules and import QueryBuilder for clean, readable pipelines.\nalias PS2.API.{Query, Join, Tree}\nimport PS2.API.QueryBuilder\n\nq =\n  %Query{}\n  |\u003e collection(\"character\")\n  |\u003e term(\"name.first_lower\", \"wrel\", :starts_with)\n  |\u003e limit(12)\n  |\u003e lang(\"en\")\n  |\u003e join(\n    %Join{}\n    |\u003e collection(\"characters_online_status\")\n    |\u003e inject_at(\"online\")\n  )\n  |\u003e tree(\n    %Tree{}\n    |\u003e field(\"online.online_status\")\n    |\u003e list(true)\n  )\n\n# For large queries with many joins, you may want to split these further into separate parts:\n\nonline_status_join =\n  %Join{}\n  |\u003e collection(\"characters_online_status\")\n  |\u003e inject_at(\"online\")\n\nonline_status_tree =\n  %Tree{}\n  |\u003e field(\"online.online_status\")\n  |\u003e list(true)\n\nq =\n  %Query{}\n  |\u003e collection(\"character\")\n  |\u003e term(\"name.first_lower\", \"wrel\", :starts_with)\n  |\u003e limit(12)\n  |\u003e lang(\"en\")\n  |\u003e join(online_status_join)\n  |\u003e tree(online_status_tree)\n```\n\nQueries are sent to the API with `PS2.API.query/1`,\nreturning `{:ok, results}`.\n\n### Nesting `Join`s\n\n`Join`s can be nested within one another using `join/2`. For\nexample:\n\n```elixir\nalias PS2.API.{Query, Join, Tree}\nimport PS2.API.QueryBuilder\n\n# Note we can pass the collection name (and common fields in Joins) when using a new/1 function.\n\nQuery.new(collection: \"character\")\n|\u003e show([\"character_id\", \"faction_id\"])\n|\u003e lang(\"en\")\n|\u003e join(\n  Join.new(collection: \"characters_online_status\", on: \"character_id\", inject_at: \"online\")\n)\n|\u003e join(\n  Join.new(collection: \"characters_weapon_stat\")\n  |\u003e join(\n    Join.new(collection: \"item\")\n  )\n)\n```\n\nSee the [API docs](https://census.daybreakgames.com/#query-commands)\nfor more information on joins.\n\nSee the PS2.API.QueryBuilder documentation for in-depth explanations and\nexamples.\n\n## Event Streaming\n\nDaybreak offers their [Event Streaming](https://census.daybreakgames.com/#what-is-websocket)\nservice through websockets to provide developers with live in-game\nevents as they occur. This wrapper handles the websocket connection\nand distributes parsed payloads through `PS2.SocketClient`s.\n\n### Example SocketClient Implementation\n\n```elixir\ndefmodule MyApp.EventHandler do\n  @behaviour PS2.SocketClient\n\n  @impl PS2.SocketClient\n  def handle_event({\"PlayerLogin\", payload}) do\n    IO.puts \"PlayerLogin: #{payload[\"character_id\"]}\"\n  end\n\n  # Catch-all callback.\n  @impl PS2.SocketClient\n  def handle_event({event_name, _payload}) do\n    IO.puts \"Unhandled event: #{event_name}\"\n  end\nend\n```\n\nAfter creating a client module like the above, you can start `PS2.Socket`\nand pass the client in your supervision tree:\n\n```elixir\ndefmodule MyApp.Application do\n  use Application\n\n  @impl Application\n  def start(_type, _args) do\n    subscriptions = [\n      events: [PS2.player_login],\n      worlds: [PS2.connery, PS2.miller, PS2.soltech],\n      characters: [\"all\"]\n    ]\n\n    clients = [MyApp.EventHandler]\n\n    ess_opts = [\n      subscriptions: subscriptions,\n      clients: clients,\n      service_id: YOUR_SERVICE_ID,\n      # you may also add a :name option.\n    ]\n\n    children = [\n      # ...\n      {PS2.Socket, ess_opts},\n      # ...\n    ]\n\n    opts = [strategy: :one_for_one, name: MyApp.Supervisor]\n    Supervisor.start_link(children, opts)\n  end\nend\n```\n\nThe subscription keys are:\n\n- `:events` is a list of event names\n- `:worlds` is a list of world/server IDs\n- `:characters` is a list of character IDs.\n\nThe `PS2` module provides some convenience methods for both\nevent names and world IDs. If you want to receive all events\nfor any of these keys, you can use `[\"all\"]` instead of a\nlist of specific values.\n\nSee the official [Event Streaming docs](https://census.daybreakgames.com/#what-is-websocket)\nfor more information.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbentheburrito%2Fplanetside_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbentheburrito%2Fplanetside_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbentheburrito%2Fplanetside_api/lists"}