DemandSphere Keywords API

openapi: 3.0.0
info:
  version: 5.0.0
  title: DemandSphere API v5.0 Documentation Keywords API
  description: ''
servers:
- url: https://api.demandsphere.com
  description: Production API Server
security:
- ApiKey: []
tags:
- name: Keywords
paths:
  /keywords/keyword_groups_detail/list:
    post:
      summary: Get a list of keyword groups details
      operationId: Keywords_KeywordGroupsDetail
      tags:
      - Keywords
      parameters:
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/Granularity'
      - $ref: '#/components/parameters/Order'
      - $ref: '#/components/parameters/SiteGlobalKey'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/PageNum'
      - $ref: '#/components/parameters/SortByGroupsDetail'
      - $ref: '#/components/parameters/SearchEngines'
      - $ref: '#/components/parameters/Export'
      - $ref: '#/components/parameters/Format'
      responses:
        '200':
          $ref: '#/components/responses/Response200GroupsDetail'
        '400':
          $ref: '#/components/responses/Response400'
  /keywords/keywords_performance_detail/list:
    post:
      summary: Get a list of keywords performance details
      operationId: Keywords_KeywordsPerformanceDetail
      tags:
      - Keywords
      parameters:
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/SortByPerformanceDetail'
      - $ref: '#/components/parameters/Granularity'
      - $ref: '#/components/parameters/Order'
      - $ref: '#/components/parameters/SiteGlobalKey'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/PageNum'
      - $ref: '#/components/parameters/SearchEngines'
      - $ref: '#/components/parameters/Export'
      - $ref: '#/components/parameters/Format'
      responses:
        '200':
          $ref: '#/components/responses/Response200PerformanceDetail'
        '400':
          $ref: '#/components/responses/Response400'
  /keywords/landing_matches/list:
    post:
      summary: Get a list of landing matches
      operationId: Keywords_LandingMatches
      tags:
      - Keywords
      parameters:
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/Granularity'
      - $ref: '#/components/parameters/Order'
      - $ref: '#/components/parameters/SiteGlobalKey'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/PageNum'
      - $ref: '#/components/parameters/SortByLandingMatches'
      - $ref: '#/components/parameters/SearchEngines'
      - $ref: '#/components/parameters/Export'
      - $ref: '#/components/parameters/Format'
      responses:
        '200':
          $ref: '#/components/responses/Response200LandingMatches_UnGrouped'
        '400':
          $ref: '#/components/responses/Response400'
  /keywords/local_rankings/list:
    post:
      summary: Get a list of local rankings
      operationId: Keywords_LocalRankings
      tags:
      - Keywords
      parameters:
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/Granularity'
      - $ref: '#/components/parameters/Order'
      - $ref: '#/components/parameters/SiteGlobalKey'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/PageNum'
      - $ref: '#/components/parameters/SortByLocalRankings_UnGrouped'
      - $ref: '#/components/parameters/Grouped'
      - $ref: '#/components/parameters/SearchEngines'
      - $ref: '#/components/parameters/Export'
      - $ref: '#/components/parameters/Format'
      responses:
        '200':
          $ref: '#/components/responses/Response200LocalRankings_UnGrouped'
        '400':
          $ref: '#/components/responses/Response400'
  /keywords/ranking_trends/list:
    post:
      summary: Get a list of ranking trends
      operationId: Keywords_RankingTrends
      tags:
      - Keywords
      parameters:
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/Granularity'
      - $ref: '#/components/parameters/Order'
      - $ref: '#/components/parameters/SiteGlobalKey'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/PageNum'
      - $ref: '#/components/parameters/SortByRankingTrends_UnGrouped'
      - $ref: '#/components/parameters/SortByRankingTrends_Grouped'
      - $ref: '#/components/parameters/Grouped'
      - $ref: '#/components/parameters/SearchEngines'
      - $ref: '#/components/parameters/Export'
      - $ref: '#/components/parameters/Format'
      responses:
        '200':
          $ref: '#/components/responses/Response200RankingTrends_UnGrouped'
        '400':
          $ref: '#/components/responses/Response400'
  /keywords/search_engines/list:
    post:
      summary: Get a list of search engines
      operationId: Keywords_SearchEngines
      tags:
      - Keywords
      parameters:
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/Granularity'
      - $ref: '#/components/parameters/Order'
      - $ref: '#/components/parameters/SiteGlobalKey'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/PageNum'
      - $ref: '#/components/parameters/SortBySearchEngines_Grouped'
      - $ref: '#/components/parameters/SortBySearchEngines_UnGrouped'
      - $ref: '#/components/parameters/Grouped'
      - $ref: '#/components/parameters/SearchEngines'
      - $ref: '#/components/parameters/Export'
      - $ref: '#/components/parameters/Format'
      responses:
        '200':
          $ref: '#/components/responses/Response200SearchEngines_UnGrouped'
        '400':
          $ref: '#/components/responses/Response400'
components:
  parameters:
    To:
      name: to
      in: query
      required: true
      schema:
        type: string
        description: YYYY-MM-DD
      description: YYYY-MM-DD
    Granularity:
      name: granularity
      in: query
      required: true
      schema:
        type: string
        default: daily
        enum:
        - daily
        - weekly
        - monthly
    Format:
      name: kw_format
      in: query
      required: false
      schema:
        type: string
        enum:
        - csv
        - xlsx
        description: format of exported file - Required! if export == true
      description: format of exported file - Required! if export == true
    Order:
      name: order
      in: query
      required: true
      schema:
        type: string
        items:
          type: String
        default: asc
        enum:
        - asc
        - desc
    Grouped:
      name: grouped
      in: query
      required: false
      schema:
        type: string
        enum:
        - 'true'
        description: Group keywords
      description: Group keywords
    SearchEngines:
      name: search_engines
      in: query
      required: true
      schema:
        type: string
        enum:
        - google_japan
        - yahoo_japan
        - google_us
        - yahoo_us
        - google_mx
        - yahoo_mx
        - google_ar
        - yahoo_ar
        - google_uk
        - yahoo_uk
        - google_au
        - yahoo_au
        - google_nz
        - yahoo_nz
        - google_fr
        - yahoo_fr
        - google_de
        - yahoo_de
        - google_es
        - yahoo_es
        - google_ch
        - yahoo_ch
        - google_in
        - yahoo_in
        - google_ca
        - yahoo_ca
        - google_tr
        - yahoo_tr
        - google_br
        - yahoo_br
        - google_dk
        - yahoo_dk
        - google_it
        - yahoo_it
        - google_se
        - yahoo_se
        - google_ie
        - yahoo_ie
        - google_nl
        - yahoo_nl
        - google_pt
        - yahoo_pt
        - google_gr
        - yahoo_gr
        - bing_us
        - bing_ar
        - bing_au
        - bing_br
        - bing_ca
        - bing_ch
        - bing_de
        - bing_dk
        - bing_es
        - bing_fr
        - bing_ie
        - bing_in
        - bing_it
        - bing_japan
        - bing_mx
        - bing_nl
        - bing_nz
        - bing_pt
        - bing_se
        - bing_uk
        - bing_tr
        - bing_gr
        - google_tw
        - yahoo_tw
        - baidu_tw
        - google_id
        - google_us_id
        - yahoo_id
        - google_th
        - yahoo_th
        - bing_th
        - google_sg
        - yahoo_sg
        - bing_sg
        - google_hk
        - yahoo_hk
        - bing_hk
        - google_pl
        - yahoo_pl
        - bing_pl
        - google_ve
        - yahoo_ve
        - bing_ve
        - google_za
        - yahoo_za
        - bing_za
        - google_vn
        - yahoo_vn
        - bing_vn
        - google_il
        - yahoo_il
        - bing_il
        - google_ro
        - yahoo_ro
        - bing_ro
        - google_my
        - yahoo_my
        - bing_my
        - yandex_ru
        - mail_ru
        - google_ru
        - yahoo_cz
        - yahoo_cy
        - yahoo_co
        - bing_hu
        - yahoo_qa
        - google_jo
        - bing_om
        - bing_eg
        - yahoo_no
        - google_ae
        - bing_bh
        - yahoo_kw
        - yahoo_eg
        - google_om
        - bing_jo
        - yahoo_sa
        - yahoo_hu
        - yahoo_bh
        - google_lb
        - google_fi
        - bing_qa
        - yahoo_ps
        - yahoo_ph
        - yahoo_pe
        - google_cz
        - google_cy
        - google_co
        - bing_no
        - google_qa
        - bing_lb
        - bing_ae
        - yahoo_jo
        - google_no
        - bing_sa
        - yahoo_ae
        - google_kw
        - google_eg
        - bing_ps
        - bing_ph
        - bing_pe
        - bing_fi
        - yahoo_om
        - google_sa
        - google_hu
        - google_bh
        - bing_cz
        - bing_cy
        - bing_co
        - yahoo_lb
        - yahoo_fi
        - google_ps
        - google_ph
        - google_pe
        - bing_kw
        - google_cn
        - baidu_cn
        - sogou_cn
        - google_us__iphone
        - google_us__ipad
        - google_japan__iphone
        - google_japan__ipad
        - google_au__iphone
        - google_au__ipad
        - so_360
        - google_us__nexus5
        - google_us__galaxytab
        - google_au__nexus5
        - google_au__galaxytab
        - google_japan__nexus5
        - google_japan__galaxytab
        - naver_kr
        - daum_kr
        - google_kr
        - google_sg__iphone
        - google_sg__ipad
        - google_sg__nexus5
        - google_sg__galaxytab
        - google_th__iphone
        - google_th__ipad
        - google_th__nexus5
        - google_th__galaxytab
        - google_id__iphone
        - google_id__ipad
        - google_id__nexus5
        - google_id__galaxytab
        - google_pg
        - google_tw__iphone
        - google_tw__ipad
        - google_tw__nexus5
        - google_tw__galaxytab
        - google_hk__iphone
        - google_hk__ipad
        - google_hk__nexus5
        - google_hk__galaxytab
        - google_ca__iphone
        - google_ca__ipad
        - google_ca__nexus5
        - google_ca__galaxytab
        - google_uk__iphone
        - google_uk__ipad
        - google_uk__nexus5
        - google_uk__galaxytab
        - google_cl
        - google_cl__iphone
        - google_cl__ipad
        - google_cl__nexus5
        - google_cl__galaxytab
        - google_at
        - google_at__iphone
        - google_de__iphone
        - google_it__iphone
        - google_be
        - google_be__iphone
        - google_ph__iphone
        - google_ph__nexus5
        - amazon_us
        - amazon_japan
        - google_ru__iphone
        - google_ru__nexus5
        - google_es__iphone
        - google_es__nexus5
        - google_fr__iphone
        - google_fr__nexus5
        - google_de__nexus5
        - google_it__nexus5
        - google_br__iphone
        - google_br__nexus5
        - google_ae__iphone
        - google_ae__nexus5
        - google_eg__iphone
        - google_eg__nexus5
        - google_kw__iphone
        - google_kw__nexus5
        - google_qa__iphone
        - google_qa__nexus5
        - google_sa__iphone
        - google_sa__nexus5
        - google_pl__iphone
        - google_pl__nexus5
        - google_sg_en
        - google_sg_en__iphone
        - google_sg_en__nexus5
        - google_sg_en__galaxytab
        - google_my__iphone
        - google_my__nexus5
        - google_my__galaxytab
        - google_my__ipad
        - google_hk_en
        - google_hk_en__iphone
        - google_hk_en__nexus5
        - google_hk_en__galaxytab
        - google_hk_en__ipad
        - googleimages_us
        - googleimages_us__iphone
        - googleimages_us__nexus5
        - google_kr__iphone
        - google_kr__nexus5
        - yahoo_japan__iphone
        - google_mx__iphone
        - google_mx__nexus5
        - google_mx__galaxytab
        - google_mx__ipad
    SortByRankingTrends_Grouped:
      name: sort_by
      in: query
      required: false
      schema:
        type: string
        default: tag_name
        enum:
        - tag_name
        - search_volume
        - clicks
        - impressions
        - average_position
        - ctr
        - rank
        - keywords_count
        description: 'When param: grouped == true - Required!'
      description: 'When param: grouped == true - Required!'
    SortByLocalRankings_UnGrouped:
      name: sort_by
      in: query
      required: false
      schema:
        type: string
        default: keyword_name
        enum:
        - keyword_name
        description: 'When param: grouped == false - Required!'
      description: 'When param: grouped == false - Required!'
    Export:
      name: export
      in: query
      required: false
      schema:
        type: boolean
        description: Export data to file
      description: Export data to file
    SortBySearchEngines_Grouped:
      name: sort_by
      in: query
      required: false
      schema:
        type: string
        default: tag_name
        enum:
        - tag_name
        - keywords_count
        - search_volume
        - clicks
        - impressions
        - average_position
        - ctr
        description: 'When param: grouped == true - Required!'
      description: 'When param: grouped == true - Required!'
    SortByGroupsDetail:
      name: sort_by
      in: query
      required: true
      schema:
        type: string
        default: tag_name
        enum:
        - tag_name
        - keywords_count
        - bucket0
        - bucket1
        - bucket2
        - bucket3
        - bucket4
        - bucket5
        - bucket6
        - bucket7
        - bucket8
        - projected_mo_traffic
        - search_volume
        - clicks
        - impressions
        - average_position
        - ctr
    Offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        description: Offset - starting record
      description: Offset - starting record
    SortByLandingMatches:
      name: sort_by
      in: query
      required: true
      schema:
        type: string
        default: keyword_name
        enum:
        - keyword_name
        - rank
        - rank_change
        - location_name
        - search_volume
        - landing_match
    From:
      name: from
      in: query
      required: true
      schema:
        type: string
        description: YYYY-MM-DD
      description: YYYY-MM-DD
    SiteGlobalKey:
      name: site_global_key
      in: query
      required: true
      schema:
        type: string
        description: Your site ID
      description: Your site ID
    PageNum:
      name: page_num
      in: query
      required: false
      schema:
        type: integer
        default: 1
    SortByPerformanceDetail:
      name: sort_by
      in: query
      required: true
      schema:
        type: string
        default: keyword_name
        enum:
        - keyword_name
        - rank
        - rank_change
        - page_url
        - keyword_description
        - location_name
        - rank_from
        - projected_mo_traffic
        - search_volume
        - clicks
        - impressions
        - average_position
        - ctr
    SortByRankingTrends_UnGrouped:
      name: sort_by
      in: query
      required: false
      schema:
        type: string
        default: keyword_name
        enum:
        - keyword_name
        - rank
        - location_name
        - search_volume
        - clicks
        - impressions
        - average_position
        - ctr
        description: 'When param: grouped == false - Required!'
      description: 'When param: grouped == false - Required!'
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 25
        description: Limit for returned number of records
      description: Limit for returned number of records
    SortBySearchEngines_UnGrouped:
      name: sort_by
      in: query
      required: false
      schema:
        type: string
        default: keyword_name
        enum:
        - keyword_name
        - rank
        - rank_change
        - projected_mo_traffic
        - pages_count
        - location_name
        - search_volume
        - clicks
        - impressions
        - average_position
        - ctr
        description: 'When param: grouped == false - Required!'
      description: 'When param: grouped == false - Required!'
  responses:
    Response200PerformanceDetail:
      description: success
      content:
        application/json:
          schema:
            type: object
            properties:
              tabularData:
                type: array
                items:
                  type: object
                  properties:
                    site:
                      type: string
                    search_engines:
                      type: array
                      items:
                        type: string
                    from:
                      type: string
                    to:
                      type: string
                    sort_col:
                      type: array
                      items:
                        type: string
                    sort_dir:
                      type: array
                      items:
                        type: string
                    buckets:
                      type: string
                    device_ids:
                      type: array
                      items:
                        type: integer
                    keyword_tag_ids:
                      type: array
                      items:
                        type: integer
                    keyword_tag_ids_logics:
                      type: array
                      items:
                        type: string
                    location_ids:
                      type: array
                      items:
                        type: integer
                    serp_features_ids:
                      type: array
                      items:
                        type: integer
                    serp_features_ids_for_ranks:
                      type: array
                      items:
                        type: integer
                    search_string:
                      type: string
                    only_conversion_event_ids:
                      type: array
                      items:
                        type: integer
                    application_brand:
                      type: string
                    statement_timeout:
                      type: integer
                    set_cache:
                      type: string
                    page_info:
                      type: object
                      properties:
                        returned_count:
                          type: integer
                        total_count:
                          type: integer
                    results:
                      type: array
                      items:
                        type: object
                        properties:
                          rank:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: integer
                              dataType:
                                type: string
                          rank_change:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: integer
                              dataType:
                                type: string
                          page_url:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: string
                              dataType:
                                type: string
                          keyword_description:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: string
                              dataType:
                                type: string
                          serp_features:
                            type: array
                            items:
                              type: object
                              properties:
                                label:
                                  type: string
                                value:
                                  type: string
                                dataType:
                                  type: string
                          search_volume:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: integer
                              dataType:
                                type: string
                          projected_mo_traffic:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: number
                                format: float
                              dataType:
                                type: string
                          keyword_id:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: integer
                              dataType:
                                type: string
                          location_id:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: integer
                              dataType:
                                type: string
                          keyword_name:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: string
                              dataType:
                                type: string
                          impressions:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: number
                                format: float
                              dataType:
                                type: string
                          clicks:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: number
                                format: float
                              dataType:
                                type: string
                          average_position:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: number
                                format: float
                              dataType:
                                type: string
                          ctr:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: number
                                format: float
                              dataType:
                                type: string
                          page_id:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: integer
                              dataType:
                                type: string
                          created_at:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: string
                              dataType:
                                type: string
                          updated_at:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: string
                              dataType:
                                type: string
                          search_intents:
                            type: array
                            items:
                              type: object
                              properties:
                                label:
                                  type: string
                                value:
                                  type: string
                                dataType:
                                  type: string
    Response200GroupsDetail:
      description: success
      content:
        application/json:
          schema:
            type: object
            properties:
              tabularData:
                type: array
                items:
                  type: object
                  properties:
                    site:
                      type: string
                    search_engines:
                      type: array
                      items:
                        type: string
                    from:
                      type: string
                    to:
                      type: string
                    sort_col:
                      type: array
                      items:
                        type: string
                    sort_dir:
                      type: array
                      items:
                        type: string
                    buckets:
                      type: string
                    device_ids:
                      type: array
                      items:
                        type: integer
                    keyword_tag_ids:
                      type: array
                      items:
                        type: integer
                    keyword_tag_ids_logics:
                      type: array
                      items:
                        type: string
                    location_ids:
                      type: array
                      items:
                        type: integer
                    serp_features_ids:
                      type: array
                      items:
                        type: integer
                    serp_features_ids_for_ranks:
                      type: array
                      items:
                        type: integer
                    search_string:
                      type: string
                    only_conversion_event_ids:
                      type: array
                      items:
                        type: integer
                    application_brand:
                      type: string
                    statement_timeout:
                      type: integer
                    set_cache:
                      type: string
                    page_info:
                      type: object
                      properties:
                        returned_count:
                          type: integer
                        total_count:
                          type: integer
                    results:
                      type: array
                      items:
                        type: object
                        properties:
                          keywords_count:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: integer
                              dataType:
                                type: string
                          bucket0:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: integer
                              dataType:
                                type: string
                          bucket1:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: integer
                              dataType:
                                type: string
                          bucket2:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: integer
                              dataType:
                                type: string
                          bucket3:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: integer
                              dataType:
                                type: string
                          bucket4:
                            type: object
                            properties:
                              label:
                                type: string
                              value:
                                type: integer
                              dataType:
                                type: string
                          bucket5:
                            type: object
                            properties:
                              label:
                       

# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/demandsphere/refs/heads/main/openapi/demandsphere-keywords-api-openapi.yml