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: type: string value: type: integer dataType: type: string bucket6: type: object properties: label: type: string value: type: integer dataType: type: string bucket7: type: object properties: label: type: string value: type: integer dataType: type: string bucket8: type: object properties: label: type: string value: type: integer 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: integer dataType: type: string impressions: type: object properties: label: type: string value: type: integer dataType: type: string clicks: type: object properties: label: type: string value: type: integer 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 tag_id: type: object properties: label: type: string value: type: integer dataType: type: string tag_name: type: object properties: label: type: string value: type: string 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 Response200SearchEngines_UnGrouped: 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: keyword_description: type: object properties: label: type: string value: type: string dataType: type: string impressions: type: object properties: label: type: string value: type: integer dataType: type: string clicks: type: object properties: label: type: string value: type: integer 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 search_volume: type: object properties: label: type: string value: type: integer dataType: type: string search_engine_data: type: array items: type: object properties: search_engine_name: 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: number format: float dataType: type: string projected_mo_traffic: type: object properties: label: type: string value: type: number format: float dataType: type: string page: type: object properties: id: type: object properties: label: type: string value: type: integer dataType: type: string url: type: object properties: label: type: string value: type: string dataType: type: string title: type: object properties: label: type: string value: type: string dataType: type: string keyword_id: type: integer mysql_keyword_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 location_id: type: object properties: label: type: string value: type: integer dataType: type: string Response400: description: Error content: application/json: schema: type: object Response200LocalRankings_UnGrouped: 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: keyword_name: type: object properties: label: type: string value: type: string dataType: type: string keyword_id: type: object properties: label: type: string value: type: integer dataType: type: string rankings_data: 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 Response200RankingTrends_UnGrouped: 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: keyword_description: type: object properties: label: type: string value: type: string dataType: type: string location_name: type: object properties: label: type: string value: type: string dataType: type: string impressions: type: object properties: label: type: string value: type: integer dataType: type: string clicks: type: object properties: label: type: string value: type: integer 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 search_volume: type: object properties: label: type: string value: type: integer dataType: type: string keyword_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 location_id: type: object properties: label: type: string value: type: integer dataType: type: string rankings_data: type: array items: type: object properties: label: type: string value: type: integer dataType: type: string Response200LandingMatches_UnGrouped: 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: keyword_id: type: object properties: label: type: string value: type: integer dataType: type: string keyword_description: type: object properties: label: type: string value: type: string dataType: type: string keyword_name: type: object properties: label: type: string value: type: string dataType: type: string location_id: type: object properties: label: type: string value: type: integer dataType: type: string location_name: type: object properties: label: type: string value: type: string dataType: type: string 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: type: array items: type: object properties: id: type: object properties: label: type: string value: type: integer dataType: type: string url: type: object properties: label: type: string value: type: string dataType: type: string title: 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 landing_match: type: object properties: label: type: string value: type: string dataType: type: string discovered_page: type: array items: type: object properties: id: type: object properties: label: type: string value: type: integer dataType: type: string url: type: object properties: label: type: string value: type: string dataType: type: string preferred_page: type: array items: type: object properties: id: type: object properties: label: type: string value: type: integer dataType: type: string url: type: object properties: label: type: string value: type: string 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 securitySchemes: ApiKey: type: apiKey name: api_key in: query