{ "openapi": "3.0.0", "info": { "title": "AWR API", "version": "1.0.0", "description": "Advanced Web Ranking API for managing SEO projects, rankings, and market share data" }, "servers": [ { "url": "https://api.advancedwebranking.com/v3", "description": "Production server" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "parameters": { "projectNamePath": { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "AWR-1" }, "projectIdPath": { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "2" }, "startDateQuery": { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date" }, "example": "2026-01-25" }, "stopDateQuery": { "name": "stopDate", "in": "query", "schema": { "type": "string", "format": "date" }, "example": "2026-01-28" } }, "schemas": { "Keyword": { "type": "object", "properties": { "name": { "type": "string", "description": "The keyword to track", "example": "my keyword" } }, "required": ["name"] }, "SearchEngineID": { "type": "object", "properties": { "awr_id": { "type": "integer", "description": "The search engine ID.", "example": 123 } }, "required": ["awr_id"] }, "SearchEngine": { "type": "object", "properties": { "name": { "type": "string", "description": "Search engine name.", "default": "google", "example": "google" }, "country": { "type": "string", "enum": [ "US", "UK", "DE", "FR", "IT", "JP", "RO", "ES", "GR", "BE", "MT", "NL", "TH", "AU", "SE", "SG", "AR", "IN", "ID", "CA", "BR", "DK", "MX", "RU", "KR", "BH", "CY", "EG", "AE", "IL", "JO", "KW", "LB", "OM", "QA", "SA", "TR", "AT", "CH", "HU", "NZ", "CZ", "PH", "MY", "IE", "ZA", "CO", "DO", "FI", "RS", "ME", "BA", "HR", "PL", "PT", "TW", "PE", "CL", "VE", "MA", "NO", "SI", "SK", "LV", "UA", "PR", "BO", "CR", "EE", "LU", "LT", "BG", "GT", "HN", "NG", "KE", "UG", "MU", "GH", "BD", "LK", "VN", "IS", "EC", "UY", "KZ", "LY", "PK", "CI", "TZ", "CD", "PA", "ZM", "MD", "BY", "SV", "NI", "PY", "BW", "ZW", "AO", "MZ", "CM", "ET", "AZ", "KH", "NP", "RW", "SN", "TN", "MM", "DZ", "JM", "GA", "GE", "PG", "IM", "BN", "TG", "BT", "BJ", "BF", "GM", "BI", "LA", "GG", "JE", "MN", "IQ", "PS", "FJ", "AF", "ML", "NE", "MV", "DJ", "GP", "AL", "LS", "AS", "FM", "GL", "LI", "MS", "MW", "PN", "SH", "SM", "UZ", "TD", "VG", "CV", "VC", "DM", "MK", "KG", "TJ", "TM", "MG", "NA", "SC", "BS", "BZ", "GI", "AM", "AG", "AD", "CU", "TT" ], "description": "Country code.", "default": "US", "example": "US" }, "location": { "type": "string", "description": "Geographic location for local search.", "default": "San Francisco, CA", "example": "San Francisco, CA" }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "ca", "gl", "eu", "ar", "ko", "et", "ru", "sw", "da", "fo", "ja", "pt", "pl", "vi", "zh-TW", "cs", "qu", "it", "hi", "bn", "te", "mr", "ta", "gu", "kn", "ml", "pa", "rm", "iw", "ga", "id", "uk", "el", "tr", "bg", "zh-CN", "no", "nl", "bs", "sr", "hr", "ha", "yo", "th", "af", "st", "zu", "xh", "ur", "fa", "ak", "sk", "sl", "sv", "lv", "lt", "fi", "ro", "hu", "hy" ], "description": "Language code.", "default": "en", "example": "en" }, "se_type": { "type": "string", "enum": [ "desktop universal", "desktop organic", "desktop organic and places", "desktop places", "desktop adwords", "desktop images", "desktop video", "desktop maps", "desktop news", "desktop shopping", "desktop jobs", "mobile universal", "mobile organic", "mobile images", "mobile video", "mobile news" ], "description": "Search engine type.", "default": "desktop universal", "example": "desktop universal" } }, "required": ["name"] }, "Website": { "type": "object", "properties": { "name": { "type": "string", "description": "Domain name", "example": "mydomain.com" }, "aliases": { "type": "string", "description": "Domain aliases pattern", "example": "*.mydomain.com" }, "index": { "type": "integer", "description": "Website index", "example": 1 }, "color_r": { "type": "integer", "description": "Red color component (0-255)", "minimum": 0, "maximum": 255, "example": 0 }, "color_g": { "type": "integer", "description": "Green color component (0-255)", "minimum": 0, "maximum": 255, "example": 0 }, "color_b": { "type": "integer", "description": "Blue color component (0-255)", "minimum": 0, "maximum": 255, "example": 255 }, "pages": { "type": "array", "description": "List of pages to track", "items": { "type": "object" } } }, "required": ["name"] }, "CreateProjectInput": { "type": "object", "description": "Project configuration for creating a new AWR project", "properties": { "keywords": { "type": "array", "description": "List of keywords to track", "items": { "$ref": "#/components/schemas/Keyword" } }, "searchengines": { "type": "array", "description": "List of search engines to track rankings on", "items": { "$ref": "#/components/schemas/SearchEngine" } }, "websites": { "type": "array", "description": "List of websites to track", "items": { "$ref": "#/components/schemas/Website" } } }, "required": ["keywords", "searchengines", "websites"], "example": { "keywords": [ { "name": "my first keyword" }, { "name": "my second keyword" } ], "searchengines": [ { "name": "google", "country": "US", "location": "San Francisco, CA", "language": "en", "se_type": "desktop universal" } ], "websites": [ { "name": "mydomain.com", "aliases": "*.mydomain.com", "index": 1, "color_r": 0, "color_g": 0, "color_b": 255, "pages": [] } ] } }, "UpdateProjectInput": { "type": "object", "description": "Project configuration for updating an existing AWR project", "properties": { "keywords": { "type": "array", "description": "List of keywords to track", "items": { "$ref": "#/components/schemas/Keyword" } }, "websites": { "type": "array", "description": "List of websites to track", "items": { "$ref": "#/components/schemas/Website" } }, "addSearchengines": { "type": "array", "description": "List of search engines to add to the project.", "items": { "$ref": "#/components/schemas/SearchEngine" } }, "removeSearchengines": { "type": "array", "description": "List of search engines to remove from the project.", "items": { "$ref": "#/components/schemas/SearchEngineID" } } }, "required": ["keywords", "searchengines", "websites"], "example": { "keywords": [ { "name": "my first keyword" }, { "name": "my second keyword" } ], "websites": [ { "name": "mydomain.com", "aliases": "*.mydomain.com", "index": 1, "color_r": 0, "color_g": 0, "color_b": 255, "pages": [] } ], "addSearchengines": [ { "name": "google", "country": "US", "location": "San Francisco, CA", "language": "en", "se_type": "desktop universal" } ], "removeSearchengines": [ { "awr_id": 123 } ] } } }, "requestBodies": { "CreateProjectBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectInput" } } } }, "UpdateProjectBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectInput" } } } } } }, "paths": { "/projects": { "get": { "summary": "Projects", "description": "Retrieves the names of all projects that exist in your AWR account.", "operationId": "getProjects", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "Unauthorized" } }, "tags": ["Projects"] } }, "/projects/{name}/create": { "post": { "summary": "Create Project", "description": "Creates a new project with specified keywords, search engines, and websites", "operationId": "createProject", "parameters": [ { "$ref": "#/components/parameters/projectNamePath" }, { "name": "frequency", "in": "query", "required": false, "schema": { "type": "string", "enum": ["ondemand", "daily", "weekly"] }, "example": "ondemand" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "US", "UK", "DE", "FR", "IT", "JP", "RO", "ES", "GR", "BE", "MT", "NL", "TH", "AU", "SE", "SG", "AR", "IN", "ID", "CA", "BR", "DK", "MX", "RU", "KR", "BH", "CY", "EG", "AE", "IL", "JO", "KW", "LB", "OM", "QA", "SA", "TR", "AT", "CH", "HU", "NZ", "CZ", "PH", "MY", "IE", "ZA", "CO", "DO", "FI", "RS", "ME", "BA", "HR", "PL", "PT", "TW", "PE", "CL", "VE", "MA", "NO", "SI", "SK", "LV", "UA", "PR", "BO", "CR", "EE", "LU", "LT", "BG", "GT", "HN", "NG", "KE", "UG", "MU", "GH", "BD", "LK", "VN", "IS", "EC", "UY", "KZ", "LY", "PK", "CI", "TZ", "CD", "PA", "ZM", "MD", "BY", "SV", "NI", "PY", "BW", "ZW", "AO", "MZ", "CM", "ET", "AZ", "KH", "NP", "RW", "SN", "TN", "MM", "DZ", "JM", "GA", "GE", "PG", "IM", "BN", "TG", "BT", "BJ", "BF", "GM", "BI", "LA", "GG", "JE", "MN", "IQ", "PS", "FJ", "AF", "ML", "NE", "MV", "DJ", "GP", "AL", "LS", "AS", "FM", "GL", "LI", "MS", "MW", "PN", "SH", "SM", "UZ", "TD", "VG", "CV", "VC", "DM", "MK", "KG", "TJ", "TM", "MG", "NA", "SC", "BS", "BZ", "GI", "AM", "AG", "AD", "CU", "TT" ] } }, { "name": "depth", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "teamaccess", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/CreateProjectBody" }, "responses": { "200": { "description": "Project created successfully" }, "401": { "description": "Unauthorized" } }, "tags": ["Projects"] } }, "/projects/{name}/update": { "post": { "summary": "Update Project", "description": "Updates an existing project configuration", "operationId": "updateProject", "parameters": [ { "$ref": "#/components/parameters/projectNamePath" } ], "requestBody": { "$ref": "#/components/requestBodies/UpdateProjectBody" }, "responses": { "200": { "description": "Project updated successfully" } }, "tags": ["Projects"] } }, "/projects/{name}/details": { "get": { "summary": "Project Details", "description": "Retrieves detailed information about a specific project", "operationId": "getProjectDetails", "parameters": [ { "$ref": "#/components/parameters/projectNamePath" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Projects"] } }, "/projects/{name}/dates": { "get": { "summary": "Project Dates", "description": "Retrieves available dates for a project", "operationId": "getProjectDates", "parameters": [ { "$ref": "#/components/parameters/projectNamePath" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Projects"] } }, "/projects/{id}/keywords": { "get": { "summary": "Project Keywords", "description": "Retrieves keywords for a specific project", "operationId": "getProjectKeywords", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Projects"] } }, "/projects/{name}/export-rankings": { "get": { "summary": "Export Rankings", "description": "Exports ranking data for a project", "operationId": "exportRankings", "parameters": [ { "$ref": "#/components/parameters/projectNamePath" }, { "$ref": "#/components/parameters/startDateQuery" }, { "$ref": "#/components/parameters/stopDateQuery" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Exports"] } }, "/projects/{name}/export-topsites": { "get": { "summary": "Export Top Sites", "description": "Exports top sites data", "operationId": "exportTopSites", "parameters": [ { "$ref": "#/components/parameters/projectNamePath" }, { "$ref": "#/components/parameters/startDateQuery" }, { "$ref": "#/components/parameters/stopDateQuery" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Exports"] } }, "/projects/{name}/export-gsc": { "get": { "summary": "Export GSC", "description": "This operation allows you to export data stored in AWR from Google Search Console.", "operationId": "exportGSC", "parameters": [ { "$ref": "#/components/parameters/projectNamePath" }, { "$ref": "#/components/parameters/startDateQuery" }, { "$ref": "#/components/parameters/stopDateQuery" }, { "name": "device", "in": "query", "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Exports"] } }, "/projects/{name}/export-visibility": { "get": { "summary": "Export Visibility", "description": "This operation allows you to export data stored in AWR from Google Search Console.", "operationId": "exportVisibility", "parameters": [ { "$ref": "#/components/parameters/projectNamePath" }, { "$ref": "#/components/parameters/startDateQuery" }, { "$ref": "#/components/parameters/stopDateQuery" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Exports"] } }, "/projects/{name}/export-pages": { "get": { "summary": "Export Landing Pages", "description": "This operation allows you to export data stored in AWR from Google Search Console.", "operationId": "exportPages", "parameters": [ { "$ref": "#/components/parameters/projectNamePath" }, { "$ref": "#/components/parameters/startDateQuery" }, { "$ref": "#/components/parameters/stopDateQuery" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Exports"] } }, "/projects/{name}/export-ctr": { "post": { "summary": "Export CTR", "description": "This operation allows you to export data stored in AWR from Google Search Console.", "operationId": "exportCTR", "parameters": [ { "$ref": "#/components/parameters/projectNamePath" }, { "name": "inputs", "in": "query", "required": true, "schema": { "type": "string" }, "description": "JSON string containing CTR export configuration", "example": "{\"date\":\"2025-12-15\",\"searches-type\":\"allSearches\",\"value\":\"exact\",\"device\":\"allDevices\",\"audience\":\"international\",\"format\":\"json\"}" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Exports"] } }, "/projects/{id}/export-search-volume": { "get": { "summary": "Export Search Volume", "description": "This operation allows you to export data stored in AWR from Google Search Console.", "operationId": "exportSearchVolume", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dataType", "in": "query", "schema": { "type": "string" }, "example": "searchVolume" }, { "name": "mode", "in": "query", "schema": { "type": "string" }, "example": "plain" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Exports"] } }, "/projects/{id}/export-keyword-difficulty": { "get": { "summary": "Export Keyword Difficulty", "description": "This operation allows you to export data stored in AWR from Google Search Console.", "operationId": "exportKeywordDifficulty", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dataType", "in": "query", "schema": { "type": "string" }, "example": "searchVolume" }, { "name": "mode", "in": "query", "schema": { "type": "string" }, "example": "plain" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Exports"] } }, "/on-demand/{name}/estimate": { "get": { "summary": "Estimate Ranking Update", "description": "This operation indicates the number of keyword units required by an on demand update for one or more projects. The output is returned in JSON format.", "operationId": "estimateRankingUpdate", "parameters": [ { "$ref": "#/components/parameters/projectNamePath" }, { "name": "speed", "in": "query", "schema": { "type": "string", "enum": ["slow", "fast"] }, "example": "slow" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Ranking Updates"] } }, "/on-demand/{name}/run": { "get": { "summary": "Run Ranking Update", "description": "This operation requests an on demand update for one or multiple projects. The output is returned in JSON format.", "operationId": "runRankingUpdate", "parameters": [ { "$ref": "#/components/parameters/projectNamePath" }, { "name": "speed", "in": "query", "schema": { "type": "string", "enum": ["slow", "fast"] }, "example": "slow" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Ranking Updates"] } }, "/keyword-difficulty/{projectIds}/estimate": { "get": { "summary": "Estimate Keyword Difficulty Update", "description": "This operation indicates the number of keyword units required by an on demand update for one or more projects. The output is returned in JSON format.", "operationId": "estimateKeywordDifficultyUpdate", "parameters": [ { "name": "projectIds", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Keyword Difficulty Updates"] } }, "/keyword-difficulty/{projectIds}/run": { "get": { "summary": "Run Keyword Difficulty Update", "description": "This operation indicates the number of keyword units required by an on demand update for one or more projects. The output is returned in JSON format.", "operationId": "runKeywordDifficultyUpdate", "parameters": [ { "name": "projectIds", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Keyword Difficulty Updates"] } }, "/marketshare/projects": { "get": { "summary": "Projects", "description": "This operation retrieves the full list of projects, with their ID and name.", "operationId": "getMarketShareProjects", "responses": { "200": { "description": "Successful response" } }, "tags": ["Market Share"] } }, "/marketshare/projects/{projectId}/search-engines": { "get": { "summary": "Search Engines", "description": "This operation retrieves the full list of search engines for a project, with their IDs and names, as displayed in the application.", "operationId": "getSearchEngines", "parameters": [ { "$ref": "#/components/parameters/projectIdPath" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Market Share"] } }, "/marketshare/projects/{projectId}/websites": { "get": { "summary": "Websites", "description": "This operation retrieves the full list of websites for a project, with their IDs and names.", "operationId": "getWebsites", "parameters": [ { "$ref": "#/components/parameters/projectIdPath" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Market Share"] } }, "/marketshare/projects/{projectId}/keyword-groups": { "get": { "summary": "Keyword Groups", "description": "This operation retrieves the full list of keyword groups for a project, with their IDs and names.", "operationId": "getKeywordGroups", "parameters": [ { "$ref": "#/components/parameters/projectIdPath" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Market Share"] } }, "/marketshare/projects/{projectId}/metadata": { "get": { "summary": "Metadata", "description": "This operation retrieves metadata for the main website and its competitors, for one or multiple dates.", "operationId": "getMetadata", "parameters": [ { "$ref": "#/components/parameters/projectIdPath" }, { "name": "searchEngineId", "in": "query", "schema": { "type": "integer" }, "example": -1 }, { "name": "keywordGroupId", "in": "query", "schema": { "type": "integer" }, "example": -1 }, { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date" }, "example": "2025-12-24" }, { "name": "stopDate", "in": "query", "schema": { "type": "string", "format": "date" }, "example": "2025-12-31" }, { "name": "mode", "in": "query", "schema": { "type": "string" }, "example": "plain" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Market Share"] } }, "/marketshare/projects/{projectId}/domain-keywords": { "get": { "summary": "Domain Keywords", "description": "This operation retrieves the keywords on which a domain was found on a specified date.", "operationId": "getDomainKeywords", "parameters": [ { "$ref": "#/components/parameters/projectIdPath" }, { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "example": "advancedwebranking.com" }, { "name": "searchEngineId", "in": "query", "schema": { "type": "integer" }, "example": -1 }, { "name": "keywordGroupId", "in": "query", "schema": { "type": "integer" }, "example": -1 }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" }, "example": "2025-12-31" }, { "name": "mode", "in": "query", "schema": { "type": "string" }, "example": "plain" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Market Share"] } }, "/marketshare/projects/{projectId}/domain-urls": { "get": { "summary": "Domain URLs", "description": "This operation retrieves a domain's URLs found on SERPS from a specified date.", "operationId": "getDomainURLs", "parameters": [ { "$ref": "#/components/parameters/projectIdPath" }, { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "example": "advancedwebranking.com" }, { "name": "searchEngineId", "in": "query", "schema": { "type": "integer" }, "example": -1 }, { "name": "keywordGroupId", "in": "query", "schema": { "type": "integer" }, "example": -1 }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" }, "example": "2025-12-31" }, { "name": "mode", "in": "query", "schema": { "type": "string" }, "example": "plain" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Market Share"] } }, "/marketshare/projects/{projectId}/url-keywords": { "get": { "summary": "URL Keywords", "description": "This operation retrieves the keywords for which an URL was ranking on a specified date.", "operationId": "getURLKeywords", "parameters": [ { "$ref": "#/components/parameters/projectIdPath" }, { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "example": "advancedwebranking.com" }, { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" }, "example": "https://www.advancedwebranking.com/rank-tracker" }, { "name": "searchEngineId", "in": "query", "schema": { "type": "integer" }, "example": -1 }, { "name": "keywordGroupId", "in": "query", "schema": { "type": "integer" }, "example": -1 }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" }, "example": "2025-12-31" }, { "name": "mode", "in": "query", "schema": { "type": "string" }, "example": "plain" } ], "responses": { "200": { "description": "Successful response" } }, "tags": ["Market Share"] } } } }