openapi: 3.0.3
info:
  title: DomDetailer Domain Metrics
  version: "2.0.0"
  description: >-
    Bulk domain metrics and backlink data. Moz, Majestic and DomDetailer's own
    Pretty crawl index returned through a single request, on pay-as-you-go
    credits that do not expire. Operating since 2015.
  contact:
    name: DomDetailer
    url: https://domdetailer.com/contact
  termsOfService: https://domdetailer.com/terms
  license:
    name: Commercial - see terms of service
    url: https://domdetailer.com/terms
servers:
  - url: https://domdetailer.com
    description: Production
tags:
  - name: Domain metrics
    description: Authority, trust and link metrics for a domain.
  - name: Backlinks
    description: Individual backlink rows and link profile summaries.
  - name: Account
    description: Credit balance. Never charged.
paths:
  /api2/checkDomain.php:
    get:
      operationId: checkDomain
      summary: "Domain metrics"
      tags:
        - "Domain metrics"
      description: >-
        Moz, Majestic and Pretty metrics for one domain in a single call.
        Consumes 1 credit per successful request. Failed requests are not charged.
      parameters:
        - name: apikey
          in: query
          required: true
          description: "Your account API key. May also be sent as an apikey header."
          schema:
            type: string
            example: "YOUR_KEY"
        - name: app
          in: query
          required: true
          description: "A short identifier for the software making the call. Used for support and usage reporting."
          schema:
            type: string
            example: "YourApp"
        - name: domain
          in: query
          required: true
          description: "The domain to look up. Send a bare hostname; protocols and a leading www. are stripped for you."
          schema:
            type: string
            example: "example.com"
        - name: forceFresh
          in: query
          required: false
          description: "Bypass the cached Moz record and refetch. Costs the same, takes longer."
          schema:
            type: string
            enum: ["0", "1"]
            example: "1"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkDomainResponse'
              example:
                {
                  "domain": "domainhuntergatherer.com",
                  "mozLinks": 16009,
                  "mozPA": 42,
                  "mozDA": 34,
                  "mozRank": 4,
                  "mozTrust": 3,
                  "mozSpam": 0,
                  "majesticStatReturned": "Default",
                  "majesticLinks": 82888,
                  "majesticRefDomains": 1849,
                  "majesticCF": 30,
                  "majesticTF": 9,
                  "majesticRefIPs": 1184,
                  "majesticRefSubnets": 969,
                  "majesticRefEdu": 0,
                  "majesticRefGov": 0,
                  "majesticTTF0Name": "News/Newspapers",
                  "majesticTTF0Value": 9,
                  "majesticTTF1Name": "Recreation/Travel",
                  "majesticTTF1Value": 5,
                  "majesticTTF2Name": "Arts/Literature",
                  "majesticTTF2Value": 5,
                  "prettyLinksIn": 504,
                  "prettyLinksOut": 2114,
                  "prettyPageCount": 364,
                  "prettyLinksEdu": 0,
                  "prettyLinksGov": 0,
                  "prettyLinksDofollow": 469
                }
        '400':
          description: "A required parameter is absent, or the domain could not be parsed as a hostname."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: "The key is missing, malformed, or not attached to an account."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: "The account has no credits left. Nothing was charged."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: "The key or email did not match any account."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: "Too many requests. The body carries retry_after in seconds - wait that long rather than retrying immediately."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: "A data source failed to respond. Safe to retry after a short pause."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: "Something went wrong on our side. If it persists, tell us what you sent."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api2/getBacklinks.php:
    get:
      operationId: getBacklinks
      summary: "Backlinks"
      tags:
        - "Backlinks"
      description: >-
        Up to 5,000 backlink rows for a domain, plus a link profile summary.
        Consumes 1 credit per successful request. Failed requests are not charged.
      parameters:
        - name: apikey
          in: query
          required: true
          description: "Your account API key."
          schema:
            type: string
            example: "YOUR_KEY"
        - name: app
          in: query
          required: true
          description: "A short identifier for your integration."
          schema:
            type: string
            example: "YourApp"
        - name: domain
          in: query
          required: true
          description: "The target domain. Send a bare hostname."
          schema:
            type: string
            example: "example.com"
        - name: onePerDomain
          in: query
          required: false
          description: "Return at most one link per referring domain. Useful for outreach lists, where a hundred links from one site are one prospect."
          schema:
            type: string
            enum: ["0", "1"]
            example: "1"
        - name: subdomain
          in: query
          required: false
          description: "Treat the value in domain as a subdomain and query it directly rather than rolling up to the registrable domain."
          schema:
            type: string
            enum: ["0", "1"]
            example: "1"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getBacklinksResponse'
              example:
                {
                  "domain": "domdetailer.com",
                  "metrics": {
                    "page_count": 364,
                    "links_in": 504,
                    "links_out": 2114,
                    "backlinks_follow": 469,
                    "backlinks_nofollow": 35,
                    "nofollow_ratio": 6.9,
                    "ref_domains": 215,
                    "links_from_gov": 0,
                    "links_from_edu": 0
                  },
                  "backlinks": [
                    {
                      "anchor": "Domdetailer.com",
                      "title": "Domdetailer.com",
                      "nf": 1,
                      "source": "https://bestfew.com/elementor-test/",
                      "target": "https://domdetailer.com/"
                    },
                    {
                      "anchor": "DomDetailer Homepage",
                      "title": "https://domdetailer.com/",
                      "nf": 0,
                      "source": "https://docu.gsa-online.de/proxy_scraper/url_metrics",
                      "target": "https://domdetailer.com/"
                    }
                  ]
                }
        '400':
          description: "A required parameter is absent, or the domain could not be parsed as a hostname."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: "The key is missing, malformed, or not attached to an account."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: "The account has no credits left. Nothing was charged."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: "The key or email did not match any account."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: "Too many requests. The body carries retry_after in seconds - wait that long rather than retrying immediately."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: "A data source failed to respond. Safe to retry after a short pause."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: "Something went wrong on our side. If it persists, tell us what you sent."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api2/checkBalance.php:
    get:
      operationId: checkBalance
      summary: "Credit balance"
      tags:
        - "Account"
      description: >-
        How many credits remain on the account. Never charged.
        This request is free and never consumes credits.
      parameters:
        - name: apikey
          in: query
          required: true
          description: "Your account API key."
          schema:
            type: string
            example: "YOUR_KEY"
        - name: app
          in: query
          required: true
          description: "A short identifier for your integration."
          schema:
            type: string
            example: "YourApp"
        - name: simple
          in: query
          required: false
          description: "Return the bare number as text/plain instead of JSON. Convenient for shell scripts."
          schema:
            type: string
            enum: ["0", "1"]
            example: "1"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkBalanceResponse'
              example:
                [
                  "UnitsLeft",
                  92921
                ]
        '400':
          description: "A required parameter is absent, or the domain could not be parsed as a hostname."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: "The key is missing, malformed, or not attached to an account."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: "The account has no credits left. Nothing was charged."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: "The key or email did not match any account."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: "Too many requests. The body carries retry_after in seconds - wait that long rather than retrying immediately."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: "A data source failed to respond. Safe to retry after a short pause."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: "Something went wrong on our side. If it persists, tell us what you sent."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: Your DomDetailer API key, from your account page.
    apiKeyHeader:
      type: apiKey
      in: header
      name: apikey
      description: The same key, sent as a header instead of a query parameter.
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Stable machine-readable slug, safe to branch on.
          example: "not_enough_credits"
        message:
          type: string
          description: Human-readable explanation.
          example: "Not enough credits."
    checkDomainResponse:
      type: object
      properties:
        domain:
          type: string
        mozDA:
          type: number
          description: "Domain Authority, 1-100."
        mozPA:
          type: number
          description: "Page Authority of the home page, 1-100."
        mozRank:
          type: number
          description: "MozRank, 0-10."
        mozTrust:
          type: number
          description: "MozTrust, 0-10."
        mozSpam:
          type: number
          description: "Spam Score, 0-17."
        mozLinks:
          type: number
          description: "External inbound links recorded by Moz."
        majesticTF:
          type: number
          description: "Trust Flow, 0-100."
        majesticCF:
          type: number
          description: "Citation Flow, 0-100."
        majesticLinks:
          type: number
          description: "External inbound links."
        majesticRefDomains:
          type: number
          description: "Unique referring domains."
        majesticRefIPs:
          type: number
          description: "Unique referring IP addresses."
        majesticRefSubnets:
          type: number
          description: "Unique referring class C subnets."
        majesticRefEdu:
          type: number
          description: "Inbound links from .edu domains."
        majesticRefGov:
          type: number
          description: "Inbound links from .gov domains."
        majesticStatReturned:
          type: string
          description: "Which Majestic dataset answered."
        majesticTTF0Name:
          type: string
          description: "First Topical Trust Flow category."
        majesticTTF0Value:
          type: number
          description: "Trust Flow within that category."
        majesticTTF1Name:
          type: string
          description: "Second Topical Trust Flow category."
        majesticTTF1Value:
          type: number
          description: "Trust Flow within that category."
        majesticTTF2Name:
          type: string
          description: "Third Topical Trust Flow category."
        majesticTTF2Value:
          type: number
          description: "Trust Flow within that category."
        prettyLinksIn:
          type: number
          description: "External inbound links our crawl has observed."
        prettyLinksOut:
          type: number
          description: "External outbound links to other domains."
        prettyPageCount:
          type: number
          description: "Pages of this domain in our index."
        prettyLinksDofollow:
          type: number
          description: "Inbound links without a nofollow attribute."
        prettyLinksEdu:
          type: number
          description: "Inbound links from .edu domains."
        prettyLinksGov:
          type: number
          description: "Inbound links from .gov domains."
    getBacklinksResponse:
      type: object
      properties:
        domain:
          type: string
        metrics:
          type: object
          properties:
            page_count:
              type: number
              description: "Pages of the target in our index."
            links_in:
              type: number
              description: "External inbound links observed."
            links_out:
              type: number
              description: "External outbound links observed."
            backlinks_follow:
              type: number
              description: "Inbound links without a nofollow attribute."
            backlinks_nofollow:
              type: number
              description: "Inbound links carrying nofollow."
            nofollow_ratio:
              type: number
              description: "Nofollow share as a percentage, 0-100."
            ref_domains:
              type: number
              description: "Unique referring domains."
            links_from_edu:
              type: number
              description: "Inbound links from .edu domains."
            links_from_gov:
              type: number
              description: "Inbound links from .gov domains."
            language_share:
              type: object
              additionalProperties:
                type: number
              description: "Optional. Percentage share per detected language across the referring pages, largest first. Omitted when we have no language data."
        backlinks:
          type: array
          items:
            type: object
            properties:
              anchor:
                type: string
                description: "Visible link text. May be empty, in which case fall back to title."
              title:
                type: string
                description: "Title of the page carrying the link."
              nf:
                type: number
                description: "1 when the link is nofollow, 0 when it is not."
              source:
                type: string
                description: "URL of the page containing the link."
              target:
                type: string
                description: "URL on the target domain being linked to."
    checkBalanceResponse:
      type: array
      description: >-
        A two-element array: the literal string "UnitsLeft" followed by the
        number of credits remaining.
      items:
        oneOf:
          - type: string
          - type: number
      example: ["UnitsLeft", 92921]
security:
  - apiKeyQuery: []
  - apiKeyHeader: []
