{"id":22307236,"url":"https://github.com/spar/piholeapiclient","last_synced_at":"2025-06-20T19:35:13.173Z","repository":{"id":40865789,"uuid":"284569031","full_name":"spar/PiHoleApiClient","owner":"spar","description":"a client for communicating with Pi-hole API","archived":false,"fork":false,"pushed_at":"2022-12-08T11:08:36.000Z","size":50,"stargazers_count":12,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-03T01:21:38.190Z","etag":null,"topics":["api","client","dns","dnssinkhole","pi-hole","pihole"],"latest_commit_sha":null,"homepage":"","language":"C#","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/spar.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}},"created_at":"2020-08-03T00:44:55.000Z","updated_at":"2024-01-07T21:24:31.000Z","dependencies_parsed_at":"2023-01-25T02:45:12.862Z","dependency_job_id":null,"html_url":"https://github.com/spar/PiHoleApiClient","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spar%2FPiHoleApiClient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spar%2FPiHoleApiClient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spar%2FPiHoleApiClient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spar%2FPiHoleApiClient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spar","download_url":"https://codeload.github.com/spar/PiHoleApiClient/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227990375,"owners_count":17852266,"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":["api","client","dns","dnssinkhole","pi-hole","pihole"],"created_at":"2024-12-03T20:09:07.988Z","updated_at":"2024-12-03T20:09:10.117Z","avatar_url":"https://github.com/spar.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://dev.azure.com/sandeepparekh/PiHoleApiClient/_apis/build/status/PiHoleApiClient-CI?branchName=master)](https://dev.azure.com/sandeepparekh/PiHoleApiClient/_build/latest?definitionId=11\u0026branchName=master)\n# Introduction\nThis is a cross platform client for communicating with [Pi-Hole](https://pi-hole.net/) API, a network wide Ads blocking DNS Sink.\n\n## Pi-Hole Endpoints\nAvailable endpoints\n\n### **version**\nThis endpoint return Pi-hole API's version.\n\n```csharp\nvar httpClient = new HttpClient();\nvar apiClient = new PiHoleApiClient(httpClient, \"http://pi.hole/admin/api.php\", \"token\");\nvar versionObj = await apiClient.GetApiVersionAsync();\nConsole.WriteLine(versionObj.Version);\n//3\n```\n\n\n### **type**\nReturn Pi-hole API's backend Type\n\n```csharp\nvar httpClient = new HttpClient();\nvar apiClient = new PiHoleApiClient(httpClient, \"http://pi.hole/admin/api.php\", \"token\");\nvar typeObj = await apiClient.GetApiBackendTypeAsync();\nConsole.WriteLine(typeObj.Type);\n//FTL\n```\n\n### **summaryRaw**\nReturns Statistics in Raw format  \n\n```csharp\nvar httpClient = new HttpClient();\nvar apiClient = new PiHoleApiClient(httpClient, \"http://pi.hole/admin/api.php\", \"token\");\nvar summaryRaw = await apiClient.GetSummaryRawAsync();\nConsole.WriteLine(JsonConvert.SerializeObject(summaryRaw));\n```\nOutput\n```json\n{\n    \"domains_being_blocked\": 85674,\n    \"dns_queries_today\": 1700,\n    \"ads_blocked_today\": 304,\n    \"ads_percentage_today\": 17.882353,\n    \"unique_domains\": 2407,\n    \"queries_forwarded\": 981,\n    \"queries_cached\": 403,\n    \"clients_ever_seen\": 4,\n    \"unique_clients\": 1,\n    \"dns_queries_all_types\": 1700,\n    \"reply_NODATA\": 355,\n    \"reply_NXDOMAIN\": 105,\n    \"reply_CNAME\": 1173,\n    \"reply_IP\": 924,\n    \"privacy_level\": 0,\n    \"status\": \"enabled\",\n    \"gravity_last_updated\": {\n        \"file_exists\": true,\n        \"absolute\": 1596340568,\n        \"relative\": {\n            \"days\": 2,\n            \"hours\": 21,\n            \"minutes\": 20\n        }\n    }\n}\n```\n\n### **summary**\nReturns Statistics formatted style\n\n```csharp\nvar httpClient = new HttpClient();\nvar apiClient = new PiHoleApiClient(httpClient, \"http://pi.hole/admin/api.php\", \"token\");\nvar summary = await apiClient.GetSummaryAsync();\nConsole.WriteLine(JsonConvert.SerializeObject(summary));\n```\nOutput\n```json\n{\n    \"domains_being_blocked\": \"85,674\",\n    \"dns_queries_today\": \"6,787\",\n    \"ads_blocked_today\": \"326\",\n    \"ads_percentage_today\": \"4.8\",\n    \"unique_domains\": \"2,262\",\n    \"queries_forwarded\": \"2,379\",\n    \"queries_cached\": \"4,064\",\n    \"clients_ever_seen\": \"4\",\n    \"unique_clients\": \"3\",\n    \"dns_queries_all_types\": \"6,787\",\n    \"reply_NODATA\": \"1,827\",\n    \"reply_NXDOMAIN\": \"1,464\",\n    \"reply_CNAME\": \"1,432\",\n    \"reply_IP\": \"2,669\",\n    \"privacy_level\": \"0\",\n    \"status\": \"enabled\",\n    \"gravity_last_updated\": {\n        \"file_exists\": true,\n        \"absolute\": 1596340568,\n        \"relative\": {\n            \"days\": 2,\n            \"hours\": 2,\n            \"minutes\": 48\n        }\n    }\n}\n```\n\n### **overTimeData10mins**\nReturns domains and ads data over 10 min. Useful for showing graphs\n\n```csharp\nvar httpClient = new HttpClient();\nvar apiClient = new PiHoleApiClient(httpClient, \"http://pi.hole/admin/api.php\", \"token\");\nvar data = await apiClient.GetOverTimeData10minsAsync();\nConsole.WriteLine(JsonConvert.SerializeObject(data));\n```\nOutput\n```json\n{\n    \"domains_over_time\": {\n        \"1596438300\": 66,\n        \"1596438900\": 64,\n        \"1596439500\": 69,\n        ...\n        \"1596521100\": 13\n    },\n    \"ads_over_time\": {\n        \"1596438300\": 8,\n        \"1596438900\": 0,\n        ...\n        \"1596521100\": 0\n    }\n}\n```\n\n### **topItems**\nReturns tops domains and top ads data\n\n```csharp\nvar httpClient = new HttpClient();\nvar apiClient = new PiHoleApiClient(httpClient, \"http://pi.hole/admin/api.php\", \"token\");\nvar data = await apiClient.GetTopItemsAsync();\nConsole.WriteLine(JsonConvert.SerializeObject(data));\n```\nOutput\n```json\n{\n    \"top_queries\": {\n        \"polling.bbc.co.uk\": 92,\n        \"wpad.reddog.microsoft.com\": 80,\n        \"www.bing.com\": 60,\n        \"www.msftncsi.com\": 31,\n    },\n    \"top_ads\": {\n        \"g.msn.com\": 534,\n        \"g.live.com\": 64,\n        \"vortex.data.microsoft.com\": 20,\n        \"c.msn.com\": 16,\n        \"watson.telemetry.microsoft.com\": 8,\n        \"web.vortex.data.microsoft.com\": 4,\n        \"otf.msn.com\": 2,\n        \"www.googletagservices.com\": 2,\n        \"mybbc-analytics.files.bbci.co.uk\": 2\n    }\n}\n```\n\n### **topClients**\nReturns tops clients list\n\n```csharp\nvar httpClient = new HttpClient();\nvar apiClient = new PiHoleApiClient(httpClient, \"http://pi.hole/admin/api.php\", \"token\");\nvar data = await apiClient.GetTopClientsAsync();\nConsole.WriteLine(JsonConvert.SerializeObject(data));\n```\nOutput\n```json\n{\n    \"top_sources\": {\n        \"win10|10.0.1.1\": 1409\n    }\n}\n```\n\n### **getForwardDestinations**\nShows number of queries that have been forwarded and the target\n\n```csharp\nvar httpClient = new HttpClient();\nvar apiClient = new PiHoleApiClient(httpClient, \"http://pi.hole/admin/api.php\", \"token\");\nvar data = await apiClient.GetForwardDestinationsAsync();\nConsole.WriteLine(JsonConvert.SerializeObject(data));\n```\nOutput\n```json\n{\n    \"forward_destinations\": {\n        \"blocklist|blocklist\": 4.22,\n        \"cache|cache\": 61.69,\n        \"one.one.one.one|1.1.1.1\": 21.7,\n        \"one.one.one.one|1.0.0.1\": 18.1\n    }\n}\n```\n\n### **getQueryTypes**\nGet queries types processed by pi-hole\n\n```csharp\nvar httpClient = new HttpClient();\nvar apiClient = new PiHoleApiClient(httpClient, \"http://pi.hole/admin/api.php\", \"token\");\nvar data = await apiClient.GetQueryTypesAsync();\nConsole.WriteLine(JsonConvert.SerializeObject(data));\n```\nOutput\n```json\n{\n    \"querytypes\": {\n        \"A (IPv4)\": 73.4,\n        \"AAAA (IPv6)\": 25.27,\n        \"ANY\": 0,\n        \"SRV\": 0.49,\n        \"SOA\": 0,\n        \"PTR\": 0.83,\n        \"TXT\": 0,\n        \"NAPTR\": 0\n    }\n}\n```\n\n### **getAllQueries**\nreturns all DNS queries\n\n```csharp\nvar httpClient = new HttpClient();\nvar apiClient = new PiHoleApiClient(httpClient, \"http://pi.hole/admin/api.php\", \"token\");\nvar data = await apiClient.GetAllQueriesAsync();\nConsole.WriteLine(JsonConvert.SerializeObject(data));\n```\nOutput\n```json\n{\n    \"data\": [\n        [\n            \"1596348004\",\n            \"AAAA\",\n            \"mytestsite.net\",\n            \"127.0.0.1\",\n            \"2\",\n            \"0\",\n            \"4\",\n            \"26\",\n            \"N/A\",\n            \"-1\"\n        ],\n        ...\n        [\n            \"1596348004\",\n            \"A\",\n            \"mytestsite.net\",\n            \"127.0.0.1\",\n            \"3\",\n            \"0\",\n            \"1\",\n            \"1\",\n            \"N/A\",\n            \"-1\"\n        ]\n    ]\n}\n```\n### **enable**\nenables pi-hole\n\n```csharp\nvar httpClient = new HttpClient();\nvar apiClient = new PiHoleApiClient(httpClient, \"http://pi.hole/admin/api.php\", \"token\");\nvar data = await apiClient.Enable();\nConsole.WriteLine(JsonConvert.SerializeObject(data.Status));\n//enabled\n```\n\n### **disable**\ndisables pi-hole\n\n```csharp\nvar httpClient = new HttpClient();\nvar apiClient = new PiHoleApiClient(httpClient, \"http://pi.hole/admin/api.php\", \"token\");\nvar data = await apiClient.Disable(10); // disables for 10 seconds, leave empty indefinitely disable it \nConsole.WriteLine(JsonConvert.SerializeObject(data.Status));\n//diabled\n```\n\n\n### **recentBlocked**\nreturns most recently blocked domain\n\n```csharp\nvar httpClient = new HttpClient();\nvar apiClient = new PiHoleApiClient(httpClient, \"http://pi.hole/admin/api.php\", \"token\");\nvar domain = await apiClient.RecentlyBlockedAsync();\nConsole.WriteLine(JsonConvert.SerializeObject(domain));\n//someAdDomain.com\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspar%2Fpiholeapiclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspar%2Fpiholeapiclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspar%2Fpiholeapiclient/lists"}