{"id":18750850,"url":"https://github.com/aalbacetef/google-dns-api","last_synced_at":"2025-08-21T00:09:51.840Z","repository":{"id":257810073,"uuid":"867872832","full_name":"aalbacetef/google-dns-api","owner":"aalbacetef","description":"Client for the Google JSON DNS over HTTPS API. DNS in the browser!","archived":false,"fork":false,"pushed_at":"2024-10-20T11:49:18.000Z","size":159,"stargazers_count":10,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-23T22:58:48.338Z","etag":null,"topics":["browser","dns","dns-over-https","doh","google","json-api","typescript"],"latest_commit_sha":null,"homepage":"https://npmjs.com/google-dns-api","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aalbacetef.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,"zenodo":null}},"created_at":"2024-10-04T22:37:48.000Z","updated_at":"2025-05-10T15:02:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"c35b14b5-6c53-44e7-b512-96e8b09fe6bd","html_url":"https://github.com/aalbacetef/google-dns-api","commit_stats":null,"previous_names":["aalbacetef/google-dns-api"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/aalbacetef/google-dns-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aalbacetef%2Fgoogle-dns-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aalbacetef%2Fgoogle-dns-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aalbacetef%2Fgoogle-dns-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aalbacetef%2Fgoogle-dns-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aalbacetef","download_url":"https://codeload.github.com/aalbacetef/google-dns-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aalbacetef%2Fgoogle-dns-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271405572,"owners_count":24753799,"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","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["browser","dns","dns-over-https","doh","google","json-api","typescript"],"created_at":"2024-11-07T17:13:20.395Z","updated_at":"2025-08-21T00:09:51.800Z","avatar_url":"https://github.com/aalbacetef.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![CI status](https://github.com/aalbacetef/google-dns-api/actions/workflows/ci.yml/badge.svg)   [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) [![npm version](https://img.shields.io/npm/v/google-dns-api.svg)](https://www.npmjs.com/package/google-dns-api)\n\n# google-dns-api\n\n\nA TypeScript wrapper for Google's DNS over HTTPS (DoH) JSON API. \n\nThis package allows you to easily perform DNS queries (e.g. A, AAAA, MX, etc.) directly from your web application without the need for a backend server or browser extensions.\n\n## Features\n\n- **TypeScript support**: Fully typed API, offering great autocompletion and type safety when using modern IDEs.\n- **Simple to use**: Perform DNS queries with just a few lines of code. It also offers nicer and clearer wrappers around the Google Request and Response objects.\n- **No backend required**: Directly query Google's DNS API from the browser.\n- **Supports multiple DNS record types**: Query for `A`, `AAAA`, `MX`, `TXT`, `CNAME`, and more (all 32 record types supported by Google).\n\n## Installation\n\nYou can install the package via npm:\n\n```bash\nnpm install google-dns-api\n```\n\nOr using Bun:\n\n```bash\nbun add google-dns-api\n```\n\n## Usage\n\nHere’s a simple example of how to use the `google-dns-api` package to perform DNS queries.\n\n### Use the query() method \n\n```typescript\nimport { query, RecordType } from 'google-dns-api';\n\n\nquery('example.com', RecordType.NS)\n  .then((response) =\u003e {\n    console.log(response);\n  })\n  .catch((error) =\u003e {\n    console.error(error);\n  });\n```\n\nand the response would be: \n\n```typescript\n{\n  status: 0,\n  isTruncated: false,\n  isDNSSECValidated: true,\n  isCheckingDisabled: false,\n  question: [ { name: 'example.com.', type: 'NS' } ],\n  answer: [\n    {\n      name: 'example.com.',\n      type: 'NS',\n      TTL: 4399,\n      data: 'b.iana-servers.net.'\n    },\n    {\n      name: 'example.com.',\n      type: 'NS',\n      TTL: 4399,\n      data: 'a.iana-servers.net.'\n    }\n  ]\n}\n```\n\n### Response \n\nThe Response type is a convenience wrapper:\n\n```typescript\ntype Response = {\n  status: number;\n  isTruncated: boolean;\n  isDNSSECValidated: boolean;\n  isCheckingDisabled: boolean;\n  question: Question[];\n  answer?: Answer[];\n  comment?: string;\n};\n\ntype Question = {\n  name: string;\n  type: string;\n};\n\ntype Answer = {\n  name: string;\n  type: string;\n  TTL?: number;\n  data: string;\n};\n```\n\n### Helpers \n\nThere are helpers for common RecordTypes (A, TXT, MX).\n\n```typescript\nimport { queryA, queryMX, queryTXT } from 'google-dns-api';\n\nqueryA('example.com')\n  .then((response) =\u003e {\n    console.log(response);\n  })\n  .catch((error) =\u003e {\n    console.error('Error:', error);\n  });\n\nqueryMX('example.com')\n  .then((response) =\u003e {\n    console.log(response);\n  })\n  .catch((error) =\u003e {\n    console.error('Error:', error);\n  });\n\nqueryTXT('example.com')\n  .then((response) =\u003e {\n    console.log(response);\n  })\n  .catch((error) =\u003e {\n    console.error('Error:', error);\n  });\n```\n\n### Options\n\nThe `query` function also supports being passed in an `Options` object:\n\n```typescript\ntype Options = {\n  client?: Client;\n  disableChecking?: boolean;\n  contentType?: ContentType;\n  DNSSEC?: boolean;\n  EDNSClientSubnet?: string;\n  randomPadding?: string;\n};\n```\n\nInformation about each option (which can be read fully on the Google API docs: [link](https://developers.google.com/speed/public-dns/docs/doh/json)).\n\n##### client \n\ndefault: omitted \n\nUse this option to pass in a client (more on clients below). This is useful if you have set a custom logger on the client.\n\n\n##### disableChecking \n\ndefault: false\n\nIf true, disables DNSSEC validation.\n\n##### contentType \n\ndefault: \"application/x-javascript\"\n\nIf set to `application/x-javascript`, you will have the response in JSON format. Use `application/dns-message` to receive a binary DNS message in the response HTTP body instead of JSON text (Note: this is not currently supported via the `query` or `Client`).\n\n##### DNSSEC\n\ndefault: false\n\nIf true, the response will include DNSSEC records (RRSIG, NSEC, NSEC3).\n\n##### EDNSClientSubnet \n\ndefault: omitted \n\nFormat is an IP address with a subnet mask. Examples: 1.2.3.4/24, 2001:700:300::/48.\n\nIf you are using DNS-over-HTTPS because of privacy concerns, and do not want any part of your IP address to be sent to authoritative name servers for geographic location accuracy, use edns_client_subnet=0.0.0.0/0. Google Public DNS normally sends approximate network information (usually zeroing out the last part of your IPv4 address).\n\n##### randomPadding \n\nThe value of this parameter is ignored. Example: XmkMw~o_mgP2pf.gpw-Oi5dK.\n\nAPI clients concerned about possible side-channel privacy attacks using the packet sizes of HTTPS GET requests can use this to make all requests exactly the same size by padding requests with random data. To prevent misinterpretation of the URL, restrict the padding characters to the unreserved URL characters: upper- and lower-case letters, digits, hyphen, period, underscore and tilde.\n\n### Client \n\nThere is also a `Client` class, which supports passing in a `Logger` as well as setting `showRawResponse` to not return this package's wrapper `Response` but Google's. \n\nThe constructor has the signature:\n\n```typescript\nconstructor(showRawResponse: boolean = false, logger?: Logger)\n```\n\nLoggers implement the interface:\n\n```typescript\ntype LogFunc = (...params: Value[]) =\u003e void;\n\ninterface Logger {\n  log: LogFunc;\n  error: LogFunc;\n}\n```\n\nA few convenience loggers are provided: \n\n- `NoopLogger`: ignores all log/error calls\n- `ConsoleLogger`: passes log calls to `console.log` and error calls to `console.error`\n- `FnLogger`: takes in a function which will be called on every log and error call.\n\n#### Usage of FnLogger \n\n```typescript\n\ntype Which = \"log\" | \"error\";\n\nconst myFunc = (which: Which, ...params: Value[]) =\u003e {\n  // do something with this \n}\n\nconst logger = new FnLogger(fn);\nlogger.log(\"something\"); // will call myFunc(\"log\", \"something\")\n```\n\n### Using the Client \n\nThe client has a method `do` with the signature:\n\n```typescript \nasync do(req: Request): Promise\u003cResponse | google.Response\u003e\n```\n\nThe `Request` is the package's wrapper around Google's request:\n\n```typescript\ntype Request = {\n  name: string;\n  type: RecordType;\n  disableChecking?: boolean;\n  contentType?: \"application/x-javascript\" | \"application/dns-message\";\n  DNSSEC?: boolean;\n  EDNSClientSubnet?: string;\n  randomPadding?: string;\n}\n```\n\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request to suggest improvements or add new features.\n\n\n## Acknowledgements\n\nThis project uses the [Google DNS-over-HTTPS API](https://developers.google.com/speed/public-dns/docs/doh/json).\n\n---\n\nHappy querying! 🎉\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faalbacetef%2Fgoogle-dns-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faalbacetef%2Fgoogle-dns-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faalbacetef%2Fgoogle-dns-api/lists"}