{"openapi":"3.0.0","info":{"version":"1.0","title":"HV API Playground","description":"Explore the High Volume API for SERP data, keyword research, WHOIS, account information, and regions. Select an endpoint to see its parameters, request examples, and responses.\n\n## Try the API with your own key\n\nYou can read the reference and download the OpenAPI definition without an account. If you have a GeoRanker API key, choose **Sign in with API key** above, then **Connect for 30 days**. After signing in once, choose an endpoint and select **Test Request**. Your session is reused across requests and page reloads, with no need to re-enter the key.\n\nStart with **GET /user** to check that your key is accepted and view your account information. For a SERP request, use **POST /serp/new**, then use the returned ID with `GET /serp/{id}` to retrieve the result.\n\n**This playground sends real requests to the production API.** Creating SERP, keyword, or WHOIS requests may consume account credits. Enter only a key for an account you are authorized to use.\n\nYour browser session lasts **30 days** from sign-in, or until you select **Logout**. The key is kept in an encrypted HttpOnly cookie, inaccessible to page JavaScript. Test requests pass through this GeoRanker documentation server, which authenticates to the API using the `apikey` query parameter. Keys are not stored in documentation, local storage, or a third-party proxy.\n\n## Guides and downloads\n\n- [Read the product guides](/docs).\n- [Download OpenAPI YAML](/openapi.yaml).\n- [View OpenAPI JSON](/openapi.json).","termsOfService":"https://georanker.com/terms"},"servers":[{"url":"https://api.highvolume.georanker.com"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"apikey","in":"query"}},"schemas":{"SERPRequest":{"type":"object","required":["region","searchEngine"],"oneOf":[{"title":"Keyword, prompt or URL search","required":["keyword"],"properties":{"searchEngine":{"not":{"enum":["google-flights","google-hotels","google-rentals"]}}}},{"title":"Google Flights search","required":["travel"],"properties":{"searchEngine":{"enum":["google-flights"]},"travel":{"$ref":"#/components/schemas/FlightTravelRequest"}}},{"title":"Google Hotels or Vacation Rentals search","required":["travel"],"properties":{"searchEngine":{"enum":["google-hotels","google-rentals"]},"travel":{"$ref":"#/components/schemas/StayTravelRequest"}}}],"properties":{"keyword":{"type":"string","example":"pizza delivery","description":"The keyword to be used when doing the search. We will not automatically append any city name to the keyword. The search will be done using the exact same keyword sent. NOTE: This parameter cannot be encoded, we already encode on our side. Example: pizza delivery. Optional for google-flights, google-hotels and google-rentals: when omitted, the API generates a keyword from the structured travel fields."},"region":{"type":"string","example":"Los Angeles,California,United States","description":"A valid canonical region name or a ISO-3166-1 alpha-2 country code. If the name does not match with a canonical name from our list, we will try to match with its formatted name, local name, criteria id or a country code. You can check a list of valid canonical regions [in our API](https://docs.georanker.com/reference#region) or  [in the Google Geolocation](https://developers.google.com/adwords/api/docs/appendix/geotargeting) . Example: London,England,United Kingdom"},"regionSearch":{"$ref":"#/components/schemas/RegionSearch"},"priority":{"type":"string","example":"NORMAL","description":"The request's priority level. Choose one of the available  priorities: LOW, NORMAL, REALTIME and INSTANT. Pay attention to REALTIME  and INSTANT levels that double and quintuple the cost of the request,  respectively. [See more](https://docs.georanker.com/docs/services-and-costs).","default":"NORMAL"},"asynchronous":{"type":"boolean","description":"This flag controls the request's behavior. If its value is `TRUE`, the  API won't wait for a response from the Crawler, retrieving the data  immediately, otherwise, if its value is `FALSE` the API will wait for  up to 300 seconds or if the Crawler answer before the wait time finishes.  Also, if this flag is not sent within the request, the default values  will be used to: `LOW` or `NORMAL` priorities this flag will be set to  `TRUE` and `REALTIME` or `INSTANT` priorities this flag will be set to  `FALSE`. **NOTE:** We recommend to set this flag to `FALSE` if the request uses  the priority `REALTIME` or `INSTANT`.","example":true,"default":true},"searchEngine":{"type":"string","example":"google","description":"The search engine used to search the content. Complete list of available Search Engines: [sogou](https://www.sogou.com/), [googlelocal](https://www.google.com/maps), [googleimages](https://images.google.com), [bing](https://www.bing.com/), [google](https://www.google.com/), [yahoo](https://www.yahoo.com/), [naver](https://www.naver.com/), [youtube](https://www.youtube.com), [google-aimode](https://www.google.com/), [baidu](http://www.baidu.com/). Examples: sogou, googlelocal, googleimages, bing, google, yahoo, naver, youtube, google-aimode, baidu, universal, chatgpt, perplexity, google-flights, google-hotels, google-rentals","enum":["sogou","googlelocal","googleimages","bing","google","yahoo","naver","youtube","google-aimode","baidu","universal","chatgpt","perplexity","google-flights","google-hotels","google-rentals"],"default":"google"},"travel":{"type":"object","description":"Structured travel search details. Required for google-flights, google-hotels and google-rentals. The engine determines the fields: origin, destination and departureDate for flights; place, checkIn and checkOut for hotels and vacation rentals. Send an explicit region with every travel request, even when keyword is omitted. Use travel.hl for the travel search language."},"callback":{"type":"string","example":"http://www.mywebsite.com/process_serp.php mysite.com/process.php or mysite.com/process.php?youridparam={: id :}&yourtypeparam={:type:}","description":"A URL that will be called when this SERP Request is ready to be downloaded. We will do a POST HTTP request sending the id from the request in a key called 'id' and telling its type which is 'serp' to the callback URL as soon the data is ready on our database.The URL can also deliver the 'id' and 'type' information as parameters inside the URL. Examples: mysite.com/process.php or mysite.com/process.php?youridparam={: id :}&yourtypeparam={:type:}"},"callbackFormat":{"type":"string","example":"SIMPLE","description":"This flag determines if the callback response will return the type and the object id or the full object response as JSON. This flag allow two values `'SIMPLE'` or `'JSON'`. Anything different from that it will use the default value `'SIMPLE'`\n**NOTE:** This flag default value is `'SIMPLE'` but is subject to change to `'JSON'` in the near future.","default":"JSON"},"maxResults":{"type":"integer","format":"int32","example":10,"description":"The maximum amount of organic results we will collect from the search engine. The maximum value of this variable is determined by the user plan. This parameter counts only organic results. Default: Value  defined by the search engine. Max value for this parameter depends on the search engine being used, as displayed in this [link](https://docs.georanker.com/docs/api-limits).","minimum":10,"default":10,"enum":[10,20,30,40,50,60,70,80,90,100]},"isMobile":{"type":"boolean","example":false,"description":"If True, we will do the search using a mobile browser. By default, this variable is False. Note that, if a customUserAgent is set, this flag is ignored","default":false},"language":{"type":"string","example":"en","description":"The language code is following ISO 639-1 standards and must be active in our system. You can see the full list of active languages [here](https://docs.georanker.com/docs/supported-languages). If this field is not provided,we will use the default language for the country. Default: en","default":"en"},"saveRawData":{"type":"boolean","example":false,"description":"True if you want the raw data to be saved. If you use a custom user-agent, we recommend turning this flag on. Travel reports can include raw entries with type JSON and a JSON-encoded content string. That provider payload may contain more listings than the parsed flights, hotels or rentals array.","default":false},"customUserAgent":{"type":"string","example":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36","description":"**(Advanced)** Force our crawlers to use a specific User-Agent header for this SERP. By default, and in most situations, this field should be NULL. If you use a custom user-agent, our parsers may not be able to parse the results automatically. You should implement your own parser using the raw data provided, thus, please make sure the saveRawData field is true when using a custom user-agent. This field cannot have more than 250 characters."},"customUrlParameter":{"type":"array","example":"[{\"name\":\"uule\",\"value\":\"w+CAIQICI...\"}]","description":"**(Advanced)** An array of objects with \"name\" and \"value\" fields. The parameters inside the array will be appended to the end of the URLs of all requests made during the SERP resolution. The parameters should not be encoded, as the encoding will be done on our side. A Parameter with the same name of a default engine parameter will replace it. Parameters with null value will remove the corresponding orignial parameters. Some default URL parameters cannot be replaced or removed. If you plan to use this feature, please note that our parser may not work well and we recommend doing the parsing and data extraction on your side using the rawHtml flag.\n\n**Google UULE example** (precise location targeting): [{\"name\":\"uule\",\"value\":\"w+CAIQICI...\"}] — The `uule` parameter encodes a location as a Base64 string and forces Google to return results for that specific location. Generate the value using the UULE encoding standard (canonical name → Base64). Example for New York: `w+CAIQICIgTmV3IFlvcmssVW5pdGVkIFN0YXRlcw==`.","items":{"$ref":"#/components/schemas/SearchEngineParameter"}},"customCookieParameter":{"type":"array","example":"[{\"name\":\"var1\",\"value\":\"1\"},{\"name\":\"var2\",\"value\":\"2\"}]","description":"**(Advanced)** An array of objects with \"name\" and \"value\" fields. The parameters inside the array will be used along with the default search engine cookies to build the cookies header of the SERP requests. The parameters should not be encoded, as the encoding will be done on our side. A Parameter with the same name of a default engine parameter will replace it. Parameters with null value will remove the corresponding orignial parameters. Some default cookies cannot be replaced or removed. If you plan to use this feature, please note that our parser may not work well and we recommend doing the parsing and data extraction on your side using the rawHtml flag. Example: [{\"name\":\"var1\",\"value\":\"1\"},{\"name\":\"var2\",\"value\":\"2\"}].","items":{"$ref":"#/components/schemas/SearchEngineParameter"}},"voiceSearchHighFidelity":{"type":"boolean","example":false,"description":"If true, the voice search transcription will be more reliable.  Important note, this feature only works in the google voice  search engine.","default":false}}},"FlightTravelRequest":{"type":"object","required":["origin","destination","departureDate"],"properties":{"origin":{"type":"string","pattern":"^[A-Za-z]{3}$","example":"CLJ","description":"Three-letter origin airport or city code."},"destination":{"type":"string","pattern":"^[A-Za-z]{3}$","example":"LON","description":"Three-letter destination airport or city code."},"departureDate":{"type":"string","format":"date","example":"2026-12-05","description":"Departure date in YYYY-MM-DD format."},"returnDate":{"type":"string","format":"date","example":"2026-12-12","description":"Optional return date, on or after departureDate. Omit for a one-way search."},"passengers":{"type":"integer","minimum":1,"example":3,"description":"Number of passengers."},"cabin":{"type":"string","enum":["economy","premium-economy","business","first"],"default":"economy","example":"business","description":"Cabin class. The business value was verified in a direct HV request."},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","example":"USD","description":"Three-letter currency code."},"hl":{"type":"string","pattern":"^[A-Za-z]{2}$","example":"en","description":"Two-letter language code for the travel search."}}},"StayTravelRequest":{"type":"object","required":["place","checkIn","checkOut"],"properties":{"place":{"type":"string","minLength":1,"example":"Prague","description":"Destination place for a hotel or vacation rental search."},"checkIn":{"type":"string","format":"date","example":"2026-12-24","description":"Check-in date in YYYY-MM-DD format."},"checkOut":{"type":"string","format":"date","example":"2026-12-26","description":"Check-out date in YYYY-MM-DD format, after checkIn."},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","example":"EUR","description":"Three-letter currency code."},"hl":{"type":"string","pattern":"^[A-Za-z]{2}$","example":"en","description":"Two-letter language code for the travel search."}}},"FlightTravelResult":{"type":"object","description":"A normalized listing from data.flights. Fields may be absent when unavailable.","properties":{"id":{"type":"string"},"position":{"type":"integer","example":1},"universalPosition":{"type":"integer","example":1},"page":{"type":"integer","example":1},"type":{"type":"string","example":"flights"},"category":{"type":"string","example":"top_departing_flights"},"company":{"type":"string","example":"LOT"},"price":{"type":"string","example":"$1,994","description":"Price text exactly as returned; do not infer a per-passenger or trip total."},"isFile":{"type":"boolean","example":false},"departureTime":{"type":"string","example":"1:55 PM"},"arrivalTime":{"type":"string","example":"5:20 PM"},"duration":{"type":"string","example":"5 hr 25 min"},"stops":{"type":"string","example":"1 stop"},"emissions":{"type":"string","example":"926 kg CO2e"},"emissionsComparison":{"type":"string","example":"+65% emissions"},"priceType":{"type":"string","example":"round trip"},"airports":{"type":"array","items":{"type":"string"},"example":["CLJ","WAW","LHR"]}}},"StayTravelResult":{"type":"object","description":"A normalized listing from data.hotels or data.rentals. Fields may be absent when unavailable.","properties":{"id":{"type":"string"},"title":{"type":"string","example":"Volcano Spa Hotel"},"url":{"type":"string","format":"uri"},"position":{"type":"integer","example":1},"universalPosition":{"type":"integer","example":1},"page":{"type":"integer","example":1},"type":{"type":"string","example":"hotels"},"rating":{"type":"string","example":"4.6"},"reviews":{"type":"string","example":"721"},"price":{"type":"string","example":"€109","description":"Price text exactly as returned by the provider."},"isFile":{"type":"boolean","example":false},"totalPrice":{"type":"string","example":"€109 nightly","description":"Provider price wording, which can be a nightly quote rather than a stay total."},"dates":{"type":"string","example":"Dec 24 – 26"},"amenities":{"type":"array","items":{"type":"string"},"example":["Breakfast","Free Wi-Fi"]},"website":{"type":"string","format":"uri"}}},"SERPData":{"type":"object","nullable":true,"description":"Returned SERP data, or null while processing. Travel reports contain the matching flights, hotels or rentals array. Other engine-specific data fields remain available in the complete response.","properties":{"flights":{"type":"array","description":"Parsed Google Flights listings.","items":{"$ref":"#/components/schemas/FlightTravelResult"}},"hotels":{"type":"array","description":"Parsed Google Hotels listings.","items":{"$ref":"#/components/schemas/StayTravelResult"}},"rentals":{"type":"array","description":"Parsed Google Vacation Rentals listings.","items":{"$ref":"#/components/schemas/StayTravelResult"}},"raw":{"type":"array","description":"Raw provider responses when saveRawData is true. Travel responses use type JSON and a JSON-encoded content string; that content can contain more listings than the parsed travel array.","items":{"type":"object","properties":{"page":{"type":"integer","example":1},"content":{"type":"string","description":"Raw provider content. Parse as JSON when type is JSON."},"type":{"type":"string","example":"JSON"}}}}}},"SERP":{"type":"object","properties":{"id":{"type":"string","example":"d4646eb82d7067126eb08adb0672f7bb","description":"A unique id created for this SERP object. This id can be used to read or update this object."},"keyword":{"type":"string","example":"pizza delivery","description":"The keyword to be used when doing the search. We will not automatically append any city name to the keyword. The search will be done using the exact same keyword sent. NOTE: This parameter cannot be encoded, we already encode on our side. Example: pizza delivery"},"region":{"$ref":"#/components/schemas/Region"},"regionSearch":{"$ref":"#/components/schemas/RegionSearch"},"priority":{"type":"string","example":"NORMAL","description":"The request's priority level. Choose one of the available  priorities: LOW, NORMAL, REALTIME and INSTANT. Pay attention to REALTIME  and INSTANT levels that double and quintuple the cost of the request,  respectively.","default":"NORMAL"},"asynchronous":{"type":"boolean","example":true,"description":"This flag controls the request's behavior. If its value is `TRUE`, the  API won't wait for a response from the Crawler, retrieving the data  immediately, otherwise, if its value is `FALSE` the API will wait for  up to 300 seconds or if the Crawler answer before the wait time finishes.  Also, if this flag is not sent within the request, the default values  will be used to: `LOW` or `NORMAL` priorities this flag will be set to  `TRUE` and `REALTIME` or `INSTANT` priorities this flag will be set to  `FALSE`. **NOTE:** We recommend to set this flag to `FALSE` if the request uses  the priority `REALTIME` or `INSTANT`.","default":true},"archivable":{"type":"boolean","example":true,"description":"This flag determines if the data will remain in our system for a longer period. If its value is `TRUE`, data will be archived, which means it will still be accessible a few days after its generation. **NOTE:** It is `TRUE` if your \"ARCHIVE\" service  is allowed.","default":false},"searchEngine":{"type":"string","example":"google","description":"The search engine used to search the content. Complete list of available Search Engines: [sogou](https://www.sogou.com/), [googlelocal](https://www.google.com/maps), [googleimages](https://images.google.com), [bing](https://www.bing.com/), [google](https://www.google.com/), [yahoo](https://www.yahoo.com/), [naver](https://www.naver.com/), [youtube](https://www.youtube.com), [google-aimode](https://www.google.com/), [baidu](http://www.baidu.com/). Examples: sogou, googlelocal, googleimages, bing, google, yahoo, naver, youtube, google-aimode, baidu. Travel reports also use google-flights, google-hotels and google-rentals."},"travel":{"type":"object","description":"Structured travel details echoed for travel reports.","anyOf":[{"$ref":"#/components/schemas/FlightTravelRequest"},{"$ref":"#/components/schemas/StayTravelRequest"}]},"data":{"$ref":"#/components/schemas/SERPData"}}},"SearchEngineParameter":{"type":"object","properties":{"name":{"type":"string","example":"lang","description":"The name of the parameter."},"value":{"type":"string","example":"en","description":"The value of the parameter."}}},"Region":{"type":"object","required":["canonicalName","countryCode","formattedName","id","latitude","longitude","name"],"properties":{"id":{"type":"string","example":"21167","description":"Unique and persistent assigned ID for the region. Example: 167"},"name":{"type":"string","example":"New York","description":"Best available English name of the geo region. Example: New York"},"localName":{"type":"string","example":"New York City","description":"The name of the region in the local language. Example: New York City"},"formattedName":{"type":"string","example":"New York, NY, USA","description":"Fully qualified region name in a human readable format. Example: New York, NY, USA"},"canonicalName":{"type":"string","example":"New York,United States","description":"The constructed fully qualified English name consisting of the region's own name, and that of its parent and country. This is unique and should be used when sending Regions names via our API. Example: New York,United States"},"placeId":{"type":"string","example":"Ch6JOwg_06VPwokTYv534QaPC8g","description":"ID code of the region in google maps API."},"parentId":{"type":"string","example":"2840","description":"If the region is inside another region, this field contains the parent's region ID. Example: 2840"},"countryCode":{"type":"string","example":"US","description":"The ISO-3166-1 alpha-2 country code that is associated with the region. Example: US"},"type":{"type":"string","example":"State","description":"The type of the region. Example: State","enum":["airport","autonomous community","borough","canton","city","city region","congressional district","country","county","department","district","dma region","governate","municipality","neighborhood","okrug","postal code","prefecture","province","region","state","territory","tv region","union territory","university"]},"population":{"type":"integer","example":8175133,"description":"The approximate total population of the region. Example: 8173"},"latitude":{"type":"number","format":"float","example":40.712784,"description":"The latitude of the center of the region. Example: 40.837"},"longitude":{"type":"number","format":"float","example":-74.00594,"description":"The longitude of the center of the region. Example: -74.413"},"location":{"$ref":"#/components/schemas/RegionLocation"}}},"RegionLocation":{"type":"object","required":["coordinates","type"],"properties":{"type":{"type":"string","example":"Point","description":"The type of mark on map"},"coordinates":{"type":"array","example":[53.0726142,7.4232678],"description":"The longitude and latitude coordinate values","items":{"type":"number","format":"float","description":"The longitude and latitude values respectively"}}}},"RegionSearch":{"type":"object","required":["latitude","longitude","types"],"properties":{"latitude":{"type":"number","format":"float","example":7.423268,"description":"The latitude coordinate value","minimum":-90,"maximum":90},"longitude":{"type":"number","format":"float","example":53.072613,"description":"The longitude coordinate value","minimum":-180,"maximum":180},"maxDistance":{"type":"integer","format":"int32","example":12000000,"description":"Constrain the search results to a maximum distance in meters"},"types":{"type":"array","default":["autonomous community","borough","canton","city","congressional district","country","county","department","governorate","municipality","neighborhood","prefecture","province","postal code","region","state","territory","tv region","union territory"],"example":["city","country","county"],"description":"The list of allowed GeoTarget Location types","items":{"type":"string","description":"The valid GeoTarget Location type"}}},"description":"**OPTIONAL - To be used as an alternative to CANONICAL REGIONS ONLY.**  Search for the nearest Region provided by its longitude, latitude, maximum  distance in meters (optional) and a list containing the allowed target types, which are: autonomous community, canton, city, congressional district,  country, county, department, governorate, municipality, prefecture, province, region, state, territory, tv region and union territory."},"Error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","description":"The error code. Usually, we use the same standards as the HTTPS status codes. Example: 500"},"message":{"type":"string","description":"The error message generated by our API. Example: Internal Server Error"},"solution":{"type":"string","description":"A possible solution to solve this error. Example: More details about the error"}}},"KeywordRequest":{"type":"object","required":["keywords","region","source"],"properties":{"keywords":{"type":"array","description":"The list of keywords. The keyword cannot be longer than 80 characters. The list can contain up to 20 items. ","items":{"type":"string","example":"local seo"}},"url":{"type":"string","example":"https://georanker.com","description":"A valid URL from a web site that will be analyzed by Google. Keyword suggestions will automatically be retrieved based on the content of the target web site. This command must use `google` as source and the suggestions flag must be `true`. The keywords field can be used together with the URL to guide the results, or it can be left null."},"region":{"type":"string","example":"Los Angeles,California,United States","description":"A valid canonical region name or a ISO-3166-1 alpha-2 country code. If the name does not match with a canonical name from our list, we will try to match with its formatted name, local name, criteria id or a country code. You can check a list of valid canonical regions [in our API](https://docs.georanker.com/reference#region) or  [in the Google Geolocation](https://developers.google.com/adwords/api/docs/appendix/geotargeting) . Example: London,England,United Kingdom"},"regionSearch":{"$ref":"#/components/schemas/RegionSearch"},"priority":{"type":"string","example":"NORMAL","description":"The request's priority level. Choose one of the available  priorities: LOW, NORMAL, REALTIME and INSTANT. Pay attention to REALTIME  and INSTANT levels that double and quintuple the cost of the request,  respectively. [See more](https://docs.georanker.com/docs/services-and-costs).","default":"NORMAL"},"asynchronous":{"type":"boolean","example":true,"description":"This flag controls the request's behavior. If its value is `TRUE`, the  API won't wait for a response from the Crawler, retrieving the data  immediately, otherwise, if its value is `FALSE` the API will wait for  up to 300 seconds or if the Crawler answer before the wait time finishes.  Also, if this flag is not sent within the request, the default values  will be used to: `LOW` or `NORMAL` priorities this flag will be set to  `TRUE` and `REALTIME` or `INSTANT` priorities this flag will be set to  `FALSE`. **NOTE:** We recommend to set this flag to `FALSE` if the request uses  the priority `REALTIME` or `INSTANT`.","default":true},"language":{"type":"string","example":"en","description":"Two letters ISO 639-1 language code. If this field is not provided or contains an unsupported language, we will not filter by language."},"source":{"type":"string","example":"google","description":"The data source used to collect the data. If the source is not set, we will assume the data needs to come from google. Possible Values: \"google\",\"baidu\".","default":"google"},"searchPartners":{"type":"boolean","example":true,"description":"If you specify the true value in the field, the results delivered will include the search partners data. By default, search partners are not considered.","default":true},"suggestions":{"type":"boolean","example":false,"description":"If true, we will return suggestions based on the keyword list.","default":false},"callback":{"type":"string","example":"http://www.mywebsite.com/process_keyword.php","description":"A URL that will be called when this Keyword Request is ready to be downloaded. We will do a POST HTTPS request sending the id from the request in a key called 'id' and telling its type which is 'keyword' to the callback URL as soon the data is ready on our database."},"callbackFormat":{"type":"string","example":"SIMPLE","description":"This flag determines if the callback response will return the type and the object id or the full object response as JSON. This flag allow two values 'SIMPLE' or 'JSON'. Anything different from that it will use the default value 'SIMPLE'\n**NOTE:** This flag default value is `'SIMPLE'` but is subject to change to `'JSON'` in the near future."}}},"Keyword":{"type":"object","properties":{"id":{"type":"string","example":"d4646eb82d7067126eb08adb0672f7bb","description":"A unique ID created for this Keyword object. This ID can be used to read or update this object."},"keywords":{"type":"array","description":"The list of keywords. The keyword cannot be longer than 80 characters. The list can contain up to 200 items.","items":{"type":"string","example":"local seo"}},"url":{"type":"string","example":"https://georanker.com","description":"A valid URL from a web site that will be analyzed by Google. Keyword suggestions will automatically be retrieved based on the content of the target web site. This command must use `google` as source and the suggestions flag must be `true`. The keywords field can be used together with the URL to guide the results, or it can be left null."},"region":{"$ref":"#/components/schemas/Region"},"regionSearch":{"$ref":"#/components/schemas/RegionSearch"},"priority":{"type":"string","example":"NORMAL","description":"The request's priority level. Choose one of the available  priorities: LOW, NORMAL, REALTIME and INSTANT. Pay attention to REALTIME  and INSTANT levels that double and quintuple the cost of the request,  respectively.","default":"NORMAL"},"asynchronous":{"type":"boolean","example":true,"description":"This flag controls the request's behavior. If its value is `TRUE`, the  API won't wait for a response from the Crawler, retrieving the data  immediately, otherwise, if its value is `FALSE` the API will wait for  up to 300 seconds or if the Crawler answer before the wait time finishes.  Also, if this flag is not sent within the request, the default values  will be used to: `LOW` or `NORMAL` priorities this flag will be set to  `TRUE` and `REALTIME` or `INSTANT` priorities this flag will be set to  `FALSE`. **NOTE:** We recommend to set this flag to `FALSE` if the request uses  the priority `REALTIME` or `INSTANT`.","default":true},"archivable":{"type":"boolean","example":true,"description":"This flag determines if the data will remain in our system for a longer period. If its value is `TRUE`, data will be archived, which means it will still be accessible a few days after its generation. **NOTE:** It is `TRUE` if your \"ARCHIVE\" service  is allowed.","default":false},"language":{"type":"string","example":"en","description":"Two letters ISO 639-1 language code. If this field is not provided, we will not filter by language."},"source":{"type":"string","example":"google","description":"The data source used to collect the data. If the source is not set, we will assume the data needs to come from google. Possible Values: \"google\",\"baidu\".","default":"google"},"searchPartners":{"type":"boolean","example":true,"description":"If you specify the true value in the field, the results delivered will include the search partners data. By default, search partners are not considered.","default":true},"suggestions":{"type":"boolean","example":false,"description":"If true, we will return suggestions based on the keyword list.","default":false},"faulty":{"type":"boolean","example":false,"description":"True if the keyword could not be solved. The spent credits will be reversed.","default":false},"callback":{"type":"string","example":"http://www.mywebsite.com/process_keyword.php","description":"A URL that will be called when this Keyword Request is ready to be downloaded. We will do a POST HTTP request sending the id from the request in a key called 'id' and telling its type which is 'keyword' to the callback URL as soon the data is ready on our database."},"callbackFormat":{"type":"string","example":"SIMPLE","description":"This flag determines if the callback response will return the type and the object id or the full object response as JSON. This flag allow two values 'SIMPLE' or 'JSON'. Anything different from that it will use the default value 'SIMPLE'\n**NOTE:** This flag default value is `'SIMPLE'` but is subject to change to `'JSON'` in the near future."},"callbackExecuted":{"type":"boolean","example":true,"description":"Indicates if the callback URL was notified when the Keyword was solved.","default":false},"callbackFailed":{"type":"boolean","example":false,"description":"Indicates a failure on the callback URL notification."},"ready":{"type":"boolean","example":true,"description":"If this object is false, means that the Keyword data is not ready yet and we are still processing it. If true, the data can be consumed.","default":false},"isFromApi":{"type":"boolean","example":true,"description":"If true, this Keyword was created by our API","default":false},"isOverLimit":{"type":"boolean","example":false,"description":"True if the client created the request passing his account's credit limits","default":false},"createdAt":{"type":"string","format":"date-time","description":"When this Keyword was requested to be processed."},"generatedAt":{"type":"string","format":"date-time","description":"When this Keyword was executed at the data providor."},"scheduledTo":{"type":"string","format":"date-time","description":"When this Search will be processed by the crawlers."},"data":{"$ref":"#/components/schemas/KeywordData"}}},"KeywordData":{"type":"object","properties":{"totalResults":{"type":"integer","format":"int32","example":102005,"description":"The amount of results the data source returned."},"results":{"type":"array","description":"The list of results for this keyword object.","items":{"$ref":"#/components/schemas/KeywordResultItem"}}}},"KeywordResultItem":{"type":"object","required":["keyword"],"properties":{"keyword":{"type":"string","example":"local seo","description":"The keyword"},"competition":{"type":"number","example":0.56,"description":"The relative amount of competition associated with the given keyword. For Google Ads, this value will be between 0 and 1 (inclusive). For Baidu Keywords, this value will be greater than or equals to 1."},"costPerClick":{"type":"number","example":0.17,"description":"The average cost per click historically paid for the keyword. For Google Ads, the currency used is the American Dollar ($). For Baidu Keywords, the currency is the Chinese Yuan (¥)."},"searchVolume":{"type":"integer","example":1072,"description":"The approximate number of searches for the given keyword."},"searchVolumeMobileRatio":{"type":"number","example":0.863,"description":"The ratio between mobile search volume and the total search volume (mobile and PC). Null if the source dos not make distinction between mobile and PC."},"monthlySearchVolumes":{"type":"array","description":"The list containing the history of the last 12 months for keyword occurrences.","items":{"$ref":"#/components/schemas/KeywordMonthlySearchVolume"}}}},"KeywordMonthlySearchVolume":{"type":"object","properties":{"year":{"type":"integer","example":2018,"description":"Year of referred search volume."},"month":{"type":"integer","example":8,"description":"Month of referred search volume (1 to 12)."},"searchVolume":{"type":"number","example":1072,"description":"The approximate number of searches for the given keyword within a month."}}},"Whois":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","example":"example.co.uk","description":"The domain used to gather informations. Example: example.co.uk"},"tld":{"type":"string","example":"co.uk","description":"The domain's tld. If the domain is an IP address, this field will be NULL. This field never starts with a dot. Example: co.uk"},"status":{"type":"array","description":"The list of status of the domain.","items":{"type":"string","example":"clientTransferProhibited"}},"createdAt":{"type":"string","format":"date-time","example":"2006-01-19T05:00:00+0000","description":"When this domain was created."},"updatedAt":{"type":"string","format":"date-time","example":"2016-02-11T10:00:00+0000","description":"When this domain was last updated."},"expiredAt":{"type":"string","format":"date-time","example":"2017-02-11T10:00:00+0000","description":"When this domain will expire."},"nameServers":{"type":"array","description":"The list of the names of the domain. Example: example.com","items":{"type":"string","example":"ns1.example.com"}},"contacts":{"$ref":"#/components/schemas/WhoisContacts"},"rawText":{"type":"string","example":"HTTP 1.0 200 Connection established Whois Server Version 2.0 Domain names in the .com and .net domains can now be registered with many different competing registrars...","description":"The raw text of the whois request. Example: HTTP 1.0 200 Connection established Whois Server Version 2.0 Domain names in the .com and .net domains can now be registered with many different competing registrars..."},"emails":{"type":"array","description":"The email list found on the whois information of the domain.","items":{"type":"string","example":"contact@example.com"}},"registered":{"type":"boolean","example":true,"description":"True if the domain is registered."},"registrar":{"$ref":"#/components/schemas/WhoisRegistrar"},"server":{"$ref":"#/components/schemas/WhoisServerInfo"},"backlinks":{"type":"integer","format":"int32","example":13669262,"description":"The total number of backlinks that points to any domain or subdomain. Example: 13662"},"socialLinks":{"$ref":"#/components/schemas/WhoisSocialLinks"}}},"WhoisServerInfo":{"type":"object","properties":{"ip":{"type":"string","example":"216.58.219.110","description":"The IP of the domain. Example: 127.1.1.0"},"reverseDNS":{"type":"string","example":"mia07s25-in-f110.1e100.net","description":"The Reverse DNS hostname of the IP address found."},"latitude":{"type":"number","format":"float","example":40.71278,"description":"The latitude of the domain's server. Example: 40.712"},"longitude":{"type":"number","format":"float","example":-10.17778,"description":"The longitude of the domain's server. Example: -10.171"},"country":{"type":"string","example":"US","description":"The country of the domain's server. Example: US"},"city":{"type":"string","example":"Mountain View","description":"The city of the domain's server. Example: Mountain View"},"continent":{"type":"string","example":"NA","description":"The continent of the domain's server. Example: NA"},"hostingASN":{"type":"string","example":"Hosting ASN Inc.","description":"The autonomous system number. Example: Hosting ASN Inc."},"hostingPovider":{"type":"string","example":"Datacenter Example S.A.","description":"The provider of the domain's host. Example: Datacenter Example S.A."}},"description":"The server information of the domain."},"WhoisSocialLinks":{"type":"object","properties":{"facebook":{"type":"string","example":"https://www.facebook.com/example","description":"The facebook address found for the domain. Example: facebook.com/ex"},"twitter":{"type":"string","example":"https://twitter.com/example","description":"The twitter address found for the domain. Example: twitter.com/ex"},"linkedin":{"type":"string","example":"https://www.linkedin.com/in/example","description":"The linkedin address found for the domain. Example: linkedin.com/ex"}},"description":"The domain social media links. This data is only avaiable if the social links are present on the homepage of the website."},"WhoisRegistrar":{"type":"object","properties":{"name":{"type":"string","example":"EXAMPLE REGISTRAR INC.","description":"The registrar name. Example: EXAMPLE REGISTRAR INC."},"email":{"type":"string","example":"contact@example.com","description":"The registrar email. Example: ex@example.com"},"url":{"type":"string","example":"http://www.example.com","description":"The registrar url. Example: example.com"},"phone":{"type":"string","example":"554-0100-0000","description":"The registrar phone number. Example: 0100-0000"}},"description":"The registrar infomation related to the domain. "},"WhoisContacts":{"type":"object","properties":{"registrant":{"$ref":"#/components/schemas/WhoisContactsInfo"},"admin":{"$ref":"#/components/schemas/WhoisContactsInfo"},"tech":{"$ref":"#/components/schemas/WhoisContactsInfo"},"zone":{"$ref":"#/components/schemas/WhoisContactsInfo"},"billing":{"$ref":"#/components/schemas/WhoisContactsInfo"}},"description":"The contact data object related to the domain."},"WhoisContactsInfo":{"type":"object","properties":{"name":{"type":"string","example":"John Doe","description":"The name of the contact. Example: John Doe"},"org":{"type":"string","example":"Google Inc.","description":"The name of the organization. Example: Google Inc."},"email":{"type":"string","example":"contact@example.com","description":"The email address. Example: contact@ex.com"},"street":{"type":"array","description":"The address parts. Example: Rd One 123","items":{"type":"string","example":"Rd One 123"}},"postal":{"type":"string","example":"12345-000","description":"The postal code of the contact. Example: 12345-000"},"city":{"type":"string","example":"New York","description":"The city of the contact. Example: New York"},"state":{"type":"string","example":"New York","description":"The state of the contact. Example: New York"},"country":{"type":"string","example":"United States","description":"The country of the contact. Example: United States"},"phone":{"type":"string","example":"555-0100-000","description":"The phone number of the contact. Example: 0100-000"},"fax":{"type":"string","example":"555-0100-987","description":"The fax number of the contact. Example: 0100-987"}},"description":"The contact information data."},"User":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","example":"2016-07-01T00:00:00+0000","description":"When this user was created. "},"emails":{"type":"array","description":"The email list from user.","items":{"$ref":"#/components/schemas/UserEmail"}},"profile":{"$ref":"#/components/schemas/UserProfile"},"credits":{"type":"array","description":"Informations about user credits.","items":{"$ref":"#/components/schemas/UserCredit"}}}},"UserEmail":{"type":"object","properties":{"address":{"type":"string","example":"email@example.com","description":"The email user. Example: email@example.com"},"verified":{"type":"boolean","example":true,"description":"TRUE If the email was verified and FALSE if emails was not verified."}}},"UserProfile":{"type":"object","properties":{"name":{"type":"string","example":"Renan Gomes","description":"The user name. Example: Marcos Gomes"},"organization":{"type":"string","example":"GeoRanker","description":"The organization name. Example: GeoRanker"},"website":{"type":"string","example":"www.georanker.com","description":"The website name. Example: www.georanker.com"},"gender":{"type":"string","example":"Male","description":"The gender from user. Example: Male"},"countryCode":{"type":"string","example":"US","description":"The user's country code. Example: US"}}},"UserCredit":{"type":"object","properties":{"total":{"type":"integer","example":10000,"description":"The total credits from user. Example: 10000"},"remaining":{"type":"integer","example":100,"description":"The remaining credits from user. Example: 100"},"createdAt":{"type":"string","format":"date-time","example":"2016-07-01T00:00:00+0000","description":"When this credit was created."},"expiresAt":{"type":"string","format":"date-time","example":"2017-07-01T00:00:00+0000","description":"When this credit has expired."}}},"RegionList":{"type":"object","required":["items","page","total"],"properties":{"page":{"type":"integer","format":"int32","example":1,"description":"Current page number. Example: 144"},"total":{"type":"integer","format":"int32","example":144,"description":"The total amount of results for this search. Example: 144"},"items":{"type":"array","description":"The name of the region in the local language.","items":{"$ref":"#/components/schemas/Region"}}}}}},"tags":[{"name":"SERPS API","x-displayName":"SERPs"},{"name":"KEYWORDS API","x-displayName":"Keywords"},{"name":"WHOIS API","x-displayName":"WHOIS"},{"name":"user","x-displayName":"Account"},{"name":"region","x-displayName":"Regions"}],"paths":{"/serp/new":{"post":{"tags":["SERPS API"],"summary":"Create SERP","description":"Create search-engine and Google Travel reports through the GeoRanker High Volume API. Requests are asynchronous by default: submit a request, keep its report ID, then retrieve the completed result.\n\n## Endpoint and authentication\n\nPOST https\\://api.highvolume.georanker.com/serp/new?apikey=YOUR\\_API\\_KEY\n\nSend Content-Type: application/json. Keep the API key on your server and replace YOUR\\_API\\_KEY with your authorized HV API key.\n\n## Standard Google Search\n\nOrdinary search-engine requests use a keyword and region:\n\n```\n{\n  \"searchEngine\": \"google\",\n  \"keyword\": \"hotels in Prague\",\n  \"region\": \"Romania\",\n  \"maxResults\": 10,\n  \"asynchronous\": true\n}\n```\n\nFor custom geographic region searches on ordinary SERP engines, omit region so that it does not override the custom region-search settings. Google Travel requests require region.\n\n## Google Travel engines\n\nUse google-flights, google-hotels, or google-rentals with a travel object. The region field is required. A keyword is optional for these engines; the API generates a descriptive keyword when one is omitted. Send travel parameters inside travel rather than encoding them into an ordinary Google Search keyword.\n\n### Flights: round trip\n\n```\n{\n  \"searchEngine\": \"google-flights\",\n  \"region\": \"Romania\",\n  \"maxResults\": 10,\n  \"asynchronous\": true,\n  \"saveRawData\": true,\n  \"travel\": {\n    \"origin\": \"CLJ\",\n    \"destination\": \"LON\",\n    \"departureDate\": \"2026-12-05\",\n    \"returnDate\": \"2026-12-12\",\n    \"passengers\": 3,\n    \"cabin\": \"business\",\n    \"currency\": \"USD\",\n    \"hl\": \"en\"\n  }\n}\n```\n\norigin and destination are three-letter airport or city codes, such as CLJ and LON. Dates use YYYY-MM-DD. Include travel.returnDate for a round trip; omit it for a one-way search. Set the passenger count with travel.passengers, currency with travel.currency, and interface language with travel.hl.\n\nThe documented cabin values are economy, premium-economy, business, and first. The default is economy. Use the exact premium-economy spelling, including the hyphen. The business example above was verified with live HV results on 27 October 2026; the other cabin values were supplied by the engineering team and were not separately live-tested in that check.\n\n### Hotels\n\n```\n{\n  \"searchEngine\": \"google-hotels\",\n  \"region\": \"Romania\",\n  \"maxResults\": 10,\n  \"asynchronous\": true,\n  \"saveRawData\": true,\n  \"travel\": {\n    \"place\": \"Prague\",\n    \"checkIn\": \"2026-12-24\",\n    \"checkOut\": \"2026-12-26\",\n    \"currency\": \"EUR\",\n    \"hl\": \"en\"\n  }\n}\n```\n\n### Vacation rentals\n\n```\n{\n  \"searchEngine\": \"google-rentals\",\n  \"region\": \"Romania\",\n  \"maxResults\": 10,\n  \"asynchronous\": true,\n  \"saveRawData\": true,\n  \"travel\": {\n    \"place\": \"Prague\",\n    \"checkIn\": \"2026-12-24\",\n    \"checkOut\": \"2026-12-26\",\n    \"currency\": \"EUR\",\n    \"hl\": \"en\"\n  }\n}\n```\n\nHotels and rentals use a destination place and check-in/check-out dates. Use future dates when running these examples after the dates shown. Keep currency and language inside travel.\n\n## Submit a request\n\nSave one of the JSON bodies above as request.json, then submit it:\n\n```\ncurl --request POST \\\n  'https://api.highvolume.georanker.com/serp/new?apikey=YOUR_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data-binary @request.json\n```\n\nWith asynchronous: true, HTTP 200 confirms creation of a report; it does not confirm that listings are ready. Keep the returned id and inspect ready and faulty when retrieving results. If submission times out before a report ID is confirmed, do not automatically submit a duplicate paid request.\n\n## Retrieve the answer\n\nUse the returned report ID with GET https\\://api.highvolume.georanker.com/serp/YOUR\\_REPORT\\_ID?apikey=YOUR\\_API\\_KEY. While ready is false and faulty is false, wait and check the same ID again. When ready is true, inspect the dedicated data.flights, data.hotels, or data.rentals array. Travel results can have an empty data.organic array.\n\nThe Get SERP results endpoint explains the returned itinerary and property fields. saveRawData: true also retains the provider JSON in data.raw. The raw JSON may contain more listings than the normalized array limited by maxResults.\n\n## Launch availability and verification\n\nThe engineering launch announcement identified JS browser s3 as the worker serving the three travel engines with JSON output. Enablement on s1, s2, s4, and s5 was requested in that discussion and was not verified by the HV test. Integrate through the public HV endpoint shown above; no direct worker URL is required.\n\nOn 27 October 2026, direct HV requests for the three examples returned HTTP 200, ready: true, faulty: false, and ten normalized listings per engine with maxResults: 10. These were individual successful requests, not a guarantee of availability, prices, result counts, or processing time for other searches.","operationId":"addSERP","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SERPRequest"},"example":{"keyword":"pizza delivery","region":"US","searchEngine":"google","priority":"NORMAL","asynchronous":true,"maxResults":10}}},"description":"The SERP request parameters."},"responses":{"200":{"description":"SERP Request created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SERP"}}}},"400":{"description":"Bad input parameter. The error message should indicate which parameter is wrong and why. We use this error to indicate some request parameters did not pass the validation test. Wrong region, wrong search engine, etc. This error means your request is wrong in some way, retrying the same request will probably not fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":400,"message":"Bad input parameter."}}}}}},"402":{"description":"Credit limit exceeded or insufficient credits. The user exceeded their available hourly or daily requests and should try again later. Or the user account has no credits left to complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":402,"message":"Credit limit exceeded or insufficient credits."}}}}}},"403":{"description":"Bad API Key. Your key may have been mistyped or you do not have access to our API. Retrying the request will not solve the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":403,"message":"Bad API Key."}}}}}},"429":{"description":"Too many requests or connections. Your server made too many requests or opened too many connections. Please slow it down and close the unused connections. Enabling the 'keep-alive' mechanism may help to reuse connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":429,"message":"Too many requests or connections."}}}}}},"500":{"description":"Internal server error. This is a generic error for some unexpected action that might happen at our side. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":500,"message":"Internal server error."}}}}}},"502":{"description":"Internal server error due a database timeout. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":502,"message":"Internal server error due a database timeout."}}}}}},"504":{"description":"Internal server error similar to error 502. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":504,"message":"Internal server error similar to error 502."}}}}}}},"externalDocs":{"description":"Original GeoRanker reference","url":"https://docs.georanker.com/reference/addserp"}}},"/serp/new/list":{"post":{"tags":["SERPS API"],"summary":"Create SERP batch","description":"Create up to 1000 SERPs requests, that are asynchronous by default, and receive a list of incomplete SERP objects, where their IDs can be used to download the respective full data, later.\nClick **[here](https://api.highvolume.georanker.com/docs/api-examples/post-serp-new-list.json)** and  check out a JSON response example.\n\n**NOTE 1:** Every SERP request will have its callback called separately.\n**NOTE 2:** To use the custom region search, do not set the region parameter, otherwise the region will be used by default.","operationId":"addSERPList","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SERPRequest"}},"example":[{"keyword":"pizza delivery","region":"US","searchEngine":"google","priority":"NORMAL","asynchronous":true,"maxResults":10}]}},"description":"An array of SERP request parameters.","required":true},"responses":{"200":{"description":"A list of Full SERP data that was created. If the data is not ready yet for a specific SERP, the flag `ready` will be false for that object and the data field object may be null. This function ignores the SERPs that do not exist or are duplicated.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SERP"}}}}},"400":{"description":"Bad input parameter. The error message should indicate which parameter is wrong and why. We use this error to indicate some request parameters did not pass the validation test. Wrong region, wrong search engine, etc. This error means your request is wrong in some way, retrying the same request will probably not fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":400,"message":"Bad input parameter."}}}}}},"402":{"description":"Credit limit exceeded or insufficient credits. The user exceeded their available hourly or daily requests and should try again later. Or the user account has no credits left to complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":402,"message":"Credit limit exceeded or insufficient credits."}}}}}},"403":{"description":"Bad API Key. Your key may have been mistyped or you do not have access to our API. Retrying the request will not solve the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":403,"message":"Bad API Key."}}}}}},"429":{"description":"Too many requests or connections. Your server made too many requests or opened too many connections. Please slow it down and close the unused connections. Enabling the 'keep-alive' mechanism may help to reuse connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":429,"message":"Too many requests or connections."}}}}}},"500":{"description":"Internal server error. This is a generic error for some unexpected action that might happen at our side. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":500,"message":"Internal server error."}}}}}},"502":{"description":"Internal server error due a database timeout. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":502,"message":"Internal server error due a database timeout."}}}}}},"504":{"description":"Internal server error similar to error 502. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":504,"message":"Internal server error similar to error 502."}}}}}}},"externalDocs":{"description":"Original GeoRanker reference","url":"https://docs.georanker.com/reference/addserplist"}}},"/serp/{id}":{"get":{"tags":["SERPS API"],"summary":"Get SERP results","description":"Retrieve a previously created SERP report by its returned ID, including Google Flights, Google Hotels, and Google Vacation Rentals results.\n\n## Endpoint and polling\n\nGET https\\://api.highvolume.georanker.com/serp/YOUR\\_REPORT\\_ID?apikey=YOUR\\_API\\_KEY\n\n```\ncurl 'https://api.highvolume.georanker.com/serp/YOUR_REPORT_ID?apikey=YOUR_API_KEY'\n```\n\nReplace YOUR\\_REPORT\\_ID with the id returned by POST /serp/new. Use the same authorized HV account and keep the API key on your server. Retrieving an existing report does not create a new search.\n\nA report that is still processing has ready: false; data can be null. Wait and retrieve the same ID again. A completed report has ready: true. Check faulty as well, and inspect error or status fields if the request failed. HTTP 200 alone confirms an API response, not that useful listings were returned.\n\n## Google Travel response arrays\n\nRead data.flights for google-flights, data.hotels for google-hotels, and data.rentals for google-rentals. These dedicated arrays hold travel listings. data.organic may be empty for a successful travel report, so an empty organic array does not establish that the travel search returned no results.\n\nThe returned searchEngine identifies the engine. The travel object echoes the submitted travel parameters, and keyword can contain the descriptive text generated by the API.\n\n### Flight example\n\nThis is a shortened response with one representative listing; report metadata and other listings are omitted:\n\n```\n{\n  \"id\": \"YOUR_REPORT_ID\",\n  \"searchEngine\": \"google-flights\",\n  \"ready\": true,\n  \"faulty\": false,\n  \"data\": {\n    \"organic\": [],\n    \"flights\": [\n      {\n        \"position\": 1,\n        \"type\": \"flights\",\n        \"category\": \"top_departing_flights\",\n        \"company\": \"LOT\",\n        \"price\": \"$1,994\",\n        \"departureTime\": \"1:55 PM\",\n        \"arrivalTime\": \"5:20 PM\",\n        \"duration\": \"5 hr 25 min\",\n        \"stops\": \"1 stop\",\n        \"priceType\": \"round trip\",\n        \"airports\": [\"CLJ\", \"WAW\", \"LHR\"]\n      }\n    ]\n  }\n}\n```\n\nOther returned flight details can include emissions and emissionsComparison. Preserve the provider's price and priceType text; do not infer whether a quote is per passenger or for the full party from the price field alone.\n\n### Hotel example\n\n```\n{\n  \"id\": \"YOUR_REPORT_ID\",\n  \"searchEngine\": \"google-hotels\",\n  \"ready\": true,\n  \"faulty\": false,\n  \"data\": {\n    \"organic\": [],\n    \"hotels\": [\n      {\n        \"position\": 1,\n        \"type\": \"hotels\",\n        \"title\": \"Volcano Spa Hotel\",\n        \"price\": \"€109\",\n        \"totalPrice\": \"€109 nightly\",\n        \"rating\": \"4.6\",\n        \"reviews\": \"721\",\n        \"amenities\": [\"Breakfast\", \"Free Wi-Fi\"]\n      }\n    ]\n  }\n}\n```\n\n### Vacation rental example\n\n```\n{\n  \"id\": \"YOUR_REPORT_ID\",\n  \"searchEngine\": \"google-rentals\",\n  \"ready\": true,\n  \"faulty\": false,\n  \"data\": {\n    \"organic\": [],\n    \"rentals\": [\n      {\n        \"position\": 1,\n        \"type\": \"rentals\",\n        \"title\": \"Letna Garden Suites - Studio Apartment\",\n        \"price\": \"€146\",\n        \"totalPrice\": \"€146 nightly\",\n        \"rating\": \"4.3\",\n        \"reviews\": \"385\",\n        \"dates\": \"Dec 24 – 26\",\n        \"amenities\": [\"Apartment\", \"Air conditioning\"]\n      }\n    ]\n  }\n}\n```\n\nProperty rows can also include dates, a Google Travel url, and an external website when the provider supplies them. Fields may be absent. The totalPrice field can contain nightly wording; preserve that wording rather than treating the field name as proof of a full-stay total.\n\n## Raw provider JSON\n\nCreate the report with saveRawData: true to retain the provider output in data.raw. For the verified travel requests, data.raw\\[0].type was JSON and data.raw\\[0].content was a JSON-encoded string containing a listing array. Parse that string separately when you need the raw provider records. Retain its original value for debugging.\n\nmaxResults limits the normalized travel array. The saved provider JSON can contain more rows than data.flights, data.hotels, or data.rentals. A live check on 27 October 2026 returned ten normalized rows for each engine with maxResults: 10, while raw row counts differed.\n\n## Interpreting results\n\nAn empty travel array means no normalized listings were returned in that response. A missing travel array or a failed report needs inspection of the full response before drawing a conclusion. Preserve the report ID for troubleshooting and recheck the existing report before creating another paid search. Prices, itinerary availability, properties, and result counts can change between searches.","operationId":"getSERP","parameters":[{"name":"id","in":"path","description":"The SERP ID to require","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SERP Request created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SERP"}}}},"402":{"description":"Credit limit exceeded or insufficient credits. The user exceeded their available hourly or daily requests and should try again later. Or the user account has no credits left to complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":402,"message":"Credit limit exceeded or insufficient credits."}}}}}},"403":{"description":"Bad API Key. Your key may have been mistyped or you do not have access to our API. Retrying the request will not solve the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":403,"message":"Bad API Key."}}}}}},"404":{"description":"Object not found. Maybe the ID was mistyped or you are looking for a SERP or Keyword that is too old.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":404,"message":"Object not found."}}}}}},"429":{"description":"Too many requests or connections. Your server made too many requests or opened too many connections. Please slow it down and close the unused connections. Enabling the 'keep-alive' mechanism may help to reuse connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":429,"message":"Too many requests or connections."}}}}}},"500":{"description":"Internal server error. This is a generic error for some unexpected action that might happen at our side. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":500,"message":"Internal server error."}}}}}},"502":{"description":"Internal server error due a database timeout. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":502,"message":"Internal server error due a database timeout."}}}}}},"504":{"description":"Internal server error similar to error 502. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":504,"message":"Internal server error similar to error 502."}}}}}}},"externalDocs":{"description":"Original GeoRanker reference","url":"https://docs.georanker.com/reference/getserp"}}},"/serp/list":{"post":{"tags":["SERPS API"],"summary":"Get SERP batch","description":"Return a list of full SERP data based on their respective IDs. If the data from one of the SERPs listed is not ready yet, the flag `ready` will be `false`, and the `data` object field will be `null`.","operationId":"getSERPList","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"array","example":["5a19d72a1553bd652f12f833","5a19d8511553bd6530605279","5a1a04621553bd54926a4e43"],"items":{"type":"string"}}}},"description":"A list of SERP IDs","required":true},"responses":{"200":{"description":"A list of Full SERP data. If the data is not ready yet for a specific SERP, the flag `ready` will be  false for that object and the data field object may be null. This function ignores the SERPs that do  not exist or are duplicated.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SERP"}}}}},"400":{"description":"Bad input parameter. The error message should indicate which parameter is wrong and why. We use this error to indicate some request parameters did not pass the validation test. Wrong region, wrong search engine, etc. This error means your request is wrong in some way, retrying the same request will probably not fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":400,"message":"Bad input parameter."}}}}}},"403":{"description":"Bad API Key. Your key may have been mistyped or you do not have access to our API. Retrying the request will not solve the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":403,"message":"Bad API Key."}}}}}},"429":{"description":"Too many requests or connections. Your server made too many requests or opened too many connections. Please slow it down and close the unused connections. Enabling the 'keep-alive' mechanism may help to reuse connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":429,"message":"Too many requests or connections."}}}}}},"500":{"description":"Internal server error. This is a generic error for some unexpected action that might happen at our side. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":500,"message":"Internal server error."}}}}}},"502":{"description":"Internal server error due a database timeout. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":502,"message":"Internal server error due a database timeout."}}}}}},"504":{"description":"Internal server error similar to error 502. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":504,"message":"Internal server error similar to error 502."}}}}}}},"externalDocs":{"description":"Original GeoRanker reference","url":"https://docs.georanker.com/reference/getserplist"}}},"/keyword/new":{"post":{"tags":["KEYWORDS API"],"summary":"Create keyword request","description":"Create a single Keyword request, that is asynchronous by default, and receive an incomplete Keyword object, where its ID can be used to download the full data, later.\nThere are two types of keyword requests:\n**KEYWORD SEARCH VOLUME**\n\n  - INPUT: from 1 to 20 keywords; and,\n  - OUTPUT: Competition, CPC and Search Volume (monthly and annually).\n\n**NOTE:** The output will contain the exact number of keywords as the input, up to 20.\n\nClick **[here](https://api.highvolume.georanker.com/docs/api-examples/post-keyword-new-ex1.json)** to  check out a JSON response example.\n\n**NOTE:** To use the custom region search, do not set the region parameter,  otherwise the region will be used by default.","operationId":"addKeyword","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordRequest"},"example":{"keywords":["local rank tracker"],"region":"US","source":"google","priority":"NORMAL","asynchronous":true,"suggestions":false}}},"description":"The keyword request parameters","required":true},"responses":{"200":{"description":"Keyword Request created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Keyword"}}}},"400":{"description":"Bad input parameter. The error message should indicate which parameter is wrong and why. We use this error to indicate some request parameters did not pass the validation test. Wrong region, wrong search engine, etc. This error means your request is wrong in some way, retrying the same request will probably not fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":400,"message":"Bad input parameter."}}}}}},"402":{"description":"Credit limit exceeded or insufficient credits. The user exceeded their available hourly or daily requests and should try again later. Or the user account has no credits left to complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":402,"message":"Credit limit exceeded or insufficient credits."}}}}}},"403":{"description":"Bad API Key. Your key may have been mistyped or you do not have access to our API. Retrying the request will not solve the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":403,"message":"Bad API Key."}}}}}},"429":{"description":"Too many requests or connections. Your server made too many requests or opened too many connections. Please slow it down and close the unused connections. Enabling the 'keep-alive' mechanism may help to reuse connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":429,"message":"Too many requests or connections."}}}}}},"500":{"description":"Internal server error. This is a generic error for some unexpected action that might happen at our side. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":500,"message":"Internal server error."}}}}}},"502":{"description":"Internal server error due a database timeout. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":502,"message":"Internal server error due a database timeout."}}}}}},"504":{"description":"Internal server error similar to error 502. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":504,"message":"Internal server error similar to error 502."}}}}}}},"externalDocs":{"description":"Original GeoRanker reference","url":"https://docs.georanker.com/reference/addkeyword"}}},"/keyword/new/list":{"post":{"tags":["KEYWORDS API"],"summary":"Create keyword batch","description":"Create up to 1000 Keyword requests, that are asynchronous by default, and receive a list of incomplete Keyword objects, where their IDs can be used to download the respective full data, later.\nClick **[here](https://api.highvolume.georanker.com/docs/api-examples/post-keyword-new-list.json)**  to check out a JSON response example.\n**NOTE 1:** Every Keyword request will have its callback called separately.\n**NOTE 2:** To use the custom region search, do not set the region parameter,  otherwise the region will be used by default.","operationId":"addKeywordList","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/KeywordRequest"}},"example":[{"keywords":["local rank tracker"],"region":"US","source":"google","priority":"NORMAL","asynchronous":true,"suggestions":false}]}},"description":"An array of Keyword request parameters","required":true},"responses":{"200":{"description":"A list of Full Keywords data that was created. If the data is not ready yet for a specific Keyword, the flag `ready` will be false for that object and the data field object may be null. This function ignores the Keywords that do not exist or are duplicated.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Keyword"}}}}},"400":{"description":"Bad input parameter. The error message should indicate which parameter is wrong and why. We use this error to indicate some request parameters did not pass the validation test. Wrong region, wrong search engine, etc. This error means your request is wrong in some way, retrying the same request will probably not fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":400,"message":"Bad input parameter."}}}}}},"402":{"description":"Credit limit exceeded or insufficient credits. The user exceeded their available hourly or daily requests and should try again later. Or the user account has no credits left to complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":402,"message":"Credit limit exceeded or insufficient credits."}}}}}},"403":{"description":"Bad API Key. Your key may have been mistyped or you do not have access to our API. Retrying the request will not solve the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":403,"message":"Bad API Key."}}}}}},"429":{"description":"Too many requests or connections. Your server made too many requests or opened too many connections. Please slow it down and close the unused connections. Enabling the 'keep-alive' mechanism may help to reuse connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":429,"message":"Too many requests or connections."}}}}}},"500":{"description":"Internal server error. This is a generic error for some unexpected action that might happen at our side. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":500,"message":"Internal server error."}}}}}},"502":{"description":"Internal server error due a database timeout. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":502,"message":"Internal server error due a database timeout."}}}}}},"504":{"description":"Internal server error similar to error 502. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":504,"message":"Internal server error similar to error 502."}}}}}}},"externalDocs":{"description":"Original GeoRanker reference","url":"https://docs.georanker.com/reference/addkeywordlist"}}},"/keyword/{id}":{"get":{"tags":["KEYWORDS API"],"summary":"Get keyword results","description":"Return the full Keyword data based on its ID. If the data is not ready yet, the flag `ready` will be `false`, and the `data` object field will be `null`.","operationId":"getKeyword","parameters":[{"name":"id","in":"path","description":"The Keyword ID to require","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Keyword request created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Keyword"}}}},"403":{"description":"Bad API Key. Your key may have been mistyped or you do not have access to our API. Retrying the request will not solve the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":403,"message":"Bad API Key."}}}}}},"404":{"description":"Object not found. Maybe the ID was mistyped or you are looking for a SERP or Keyword that is too old.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":404,"message":"Object not found."}}}}}},"429":{"description":"Too many requests or connections. Your server made too many requests or opened too many connections. Please slow it down and close the unused connections. Enabling the 'keep-alive' mechanism may help to reuse connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":429,"message":"Too many requests or connections."}}}}}},"500":{"description":"Internal server error. This is a generic error for some unexpected action that might happen at our side. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":500,"message":"Internal server error."}}}}}},"502":{"description":"Internal server error due a database timeout. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":502,"message":"Internal server error due a database timeout."}}}}}},"504":{"description":"Internal server error similar to error 502. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":504,"message":"Internal server error similar to error 502."}}}}}}},"externalDocs":{"description":"Original GeoRanker reference","url":"https://docs.georanker.com/reference/getkeyword"}}},"/keyword/list":{"post":{"tags":["KEYWORDS API"],"summary":"Get keyword batch","description":"Return a list of full Keywords data based on their respective IDs. If the data from one of the Keywords listed is not ready yet, the flag `ready` will be `false`, and the `data` object field will be `null`.","operationId":"getKeywordList","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"string"},"example":["5a19d72a1553bd652f12f833","5a19d8511553bd6530605279","5a1a04621553bd54926a4e43"]}}},"description":"A list of Keyword IDs","required":true},"responses":{"200":{"description":"A list of Full Keyword data. If the data is not ready yet for a specific Keyword, the flag `ready` will be false for that object and the data field object may be null. This function ignores the Keywords that do not exist or are duplicated.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Keyword"}}}}},"400":{"description":"Bad input parameter. The error message should indicate which parameter is wrong and why. We use this error to indicate some request parameters did not pass the validation test. Wrong region, wrong search engine, etc. This error means your request is wrong in some way, retrying the same request will probably not fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":400,"message":"Bad input parameter."}}}}}},"403":{"description":"Bad API Key. Your key may have been mistyped or you do not have access to our API. Retrying the request will not solve the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":403,"message":"Bad API Key."}}}}}},"429":{"description":"Too many requests or connections. Your server made too many requests or opened too many connections. Please slow it down and close the unused connections. Enabling the 'keep-alive' mechanism may help to reuse connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":429,"message":"Too many requests or connections."}}}}}},"500":{"description":"Internal server error. This is a generic error for some unexpected action that might happen at our side. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":500,"message":"Internal server error."}}}}}},"502":{"description":"Internal server error due a database timeout. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":502,"message":"Internal server error due a database timeout."}}}}}},"504":{"description":"Internal server error similar to error 502. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":504,"message":"Internal server error similar to error 502."}}}}}}},"externalDocs":{"description":"Original GeoRanker reference","url":"https://docs.georanker.com/reference/getkeywordlist"}}},"/whois/{domain}":{"get":{"tags":["WHOIS API"],"summary":"Get WHOIS data","description":"Look up WHOIS information for a domain, including server details, contact information and social links when available. Returned fields depend on the domain and selected source; contacts or registrant details may be missing or redacted.\n**CREDIT USAGE**\nBase price is **1 CREDIT** per request. Additional multipliers can be applied by account-specific credit rules.\nClick **[here](https://api.highvolume.georanker.com/docs/api-examples/get-whois.json)** and  check out a JSON response example.\n\n\n## WHOIS through SEO MCP\n\nUse GeoRanker SEO MCP's `get_whois` tool with a bare domain, such as `example.com`. Optional `source` values are `auto` (default), `website` and `whois`; optional `forceLive: true` bypasses completed MCP cache reuse. The tool returns the available WHOIS data synchronously, with cache metadata and the MCP credit charge.\n\nA successful fresh query costs **10 MCP credits**. Reusing a completed cached result charges **0 MCP credits**. Failed, malformed, timed-out or cancelled lookups release or refund the reserved MCP allowance, even when the provider outcome is uncertain. MCP allowance credits are separate from the direct API account-credit rules above.\n\nThe server handles reconciliation and refund recovery, including after restart. Failures report the actual credit and reconciliation state. A refund is reported as complete only after durable accounting confirms it; accounting outages remain pending while the server retries recovery. Matching unresolved work cannot create another paid provider lookup, including with `forceLive: true`. Recovery requires no client replay or polling and also applies to compatible 0.15.0 SEO clients.\n\nExample prompt: “Look up WHOIS for example.com using source auto. Summarize the available registration and server information, contacts and social links. Flag missing fields and report the MCP credits charged.”\n\n[SEO MCP setup and examples](https://georanker.com/mcp/seo) · [MCP credits](https://georanker.com/mcp/credits)","operationId":"getWhois","parameters":[{"name":"domain","in":"path","description":"Domain name of whois data that needs to be fetched","required":true,"schema":{"type":"string"}},{"name":"source","in":"query","description":"This is the data source to generate the whois data.\nThe possible values are:\nauto: This is the default option. Our System chooses the best data source based on the domain TLD.\nwebsite: This will make the request try to be solved using the website scraping algorithm. This will only work for a small and very specific list of TLDs.\nwhois: Most of the time, we will use this data source to get the data. This is equivalent to run the whois via command line on a linux machine and, after, extract each single piece of data.\n","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The Whois object with the contact and social links information collected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Whois"}}}},"400":{"description":"Bad input parameter. The error message should indicate which parameter is wrong and why. We use this error to indicate some request parameters did not pass the validation test. Wrong region, wrong search engine, etc. This error means your request is wrong in some way, retrying the same request will probably not fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":400,"message":"Bad input parameter."}}}}}},"403":{"description":"Bad API Key. Your key may have been mistyped or you do not have access to our API. Retrying the request will not solve the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":403,"message":"Bad API Key."}}}}}},"429":{"description":"Credit limit exceeded or insufficient credits. The user exceeded their available hourly or daily requests and should try again later. Or the user account has no credits left to complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":429,"message":"Too many requests or connections."}}}}}},"500":{"description":"Internal server error. This is a generic error for some unexpected action that might happen at our side. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":500,"message":"Internal server error."}}}}}},"502":{"description":"Internal server error due a database timeout. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":502,"message":"Internal server error due a database timeout."}}}}}},"503":{"description":"Too many requests or connections. Your server made too many requests or opened too many connections. Please slow it down and close the unused connections. Enabling the 'keep-alive' mechanism may help to reuse connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":503,"message":"Too many requests or connections."}}}}}},"504":{"description":"Internal server error similar to error 502. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":504,"message":"Internal server error similar to error 502."}}}}}}},"externalDocs":{"description":"Original GeoRanker reference","url":"https://docs.georanker.com/reference/getwhois"}}},"/user":{"get":{"tags":["user"],"summary":"Get account details","description":"Read the user account information.","operationId":"getUser","parameters":[],"responses":{"200":{"description":"The user account data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"403":{"description":"Bad API Key. Your key may have been mistyped or you do not have access to our API. Retrying the request will not solve the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":403,"message":"Bad API Key."}}}}}},"429":{"description":"Too many requests or connections. Your server made too many requests or opened too many connections. Please slow it down and close the unused connections. Enabling the 'keep-alive' mechanism may help to reuse connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":429,"message":"Too many requests or connections."}}}}}},"500":{"description":"Internal server error. This is a generic error for some unexpected action that might happen at server side. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":500,"message":"Internal server error."}}}}}},"502":{"description":"Internal server error due a database timeout. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":502,"message":"Internal server error due a database timeout."}}}}}},"504":{"description":"Internal server error similar to error 502. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":504,"message":"Internal server error similar to error 502."}}}}}}},"externalDocs":{"description":"Original GeoRanker reference","url":"https://docs.georanker.com/reference/getuser"}}},"/region/list":{"get":{"tags":["region"],"summary":"List regions","description":"Read and filter a list of regions. The region list is static and can be cached on the client side.","operationId":"listRegions","parameters":[{"name":"countryCode","in":"query","description":"The two letters ISO-3166-1 alpha-2 country code to use to filter  the region list. Example: US","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","description":"The type of the region. Example: country, region or postal code","required":false,"schema":{"type":"string"}},{"name":"items","in":"query","description":"The total number of items to return on the search by the specific  page. Example: 100","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"The number of the page to download. You can paginate the results to  get more locations.  Default: 1. Example: 2","required":false,"schema":{"type":"integer"}},{"name":"query","in":"query","description":"The string containing the region's name that should be searched.  Example: Las Vegas","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The list of regions that was found using the filters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionList"}}}},"403":{"description":"Bad API Key. Your key may have been mistyped or you do not have access to our API. Retrying the request will not solve the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":403,"message":"Bad API Key."}}}}}},"500":{"description":"Internal server error. This is a generic error for some unexpected action that might happen at our side. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":500,"message":"Internal server error."}}}}}},"502":{"description":"Internal server error due a database timeout. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":502,"message":"Internal server error due a database timeout."}}}}}},"503":{"description":"Too many requests or connections. Your server made too many requests or opened too many connections. Please slow it down and close the unused connections. Enabling the 'keep-alive' mechanism may help to reuse connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":503,"message":"Too many requests or connections."}}}}}},"504":{"description":"Internal server error similar to error 502. This error should never appear to you, but if it does, you should retry later and contact us if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":504,"message":"Internal server error similar to error 502."}}}}}}},"externalDocs":{"description":"Original GeoRanker reference","url":"https://docs.georanker.com/reference/listregions"}}}}}