docs: def nominatim_request(params, type = "search", pause_duration=1, timeout=30, error_pause_duration=180):
      """
      Send a request to the Nominatim API via HTTP GET and return the JSON
      response.
  
      Parameters
      ----------
      params : dict or OrderedDict
          key-value pairs of parameters
      type : string
          Type of Nominatim query. One of the following: search, reverse or lookup
      pause_duration : int
          how long to pause before requests, in seconds
      timeout : int
          the timeout interval for the requests library
      error_pause_duration : int
          how long to pause in seconds before re-trying requests if error
  
      Returns
      -------
      response_json : dict
      """
  
      known_requests = {"search", "reverse", "lookup"}
      if type not in known_requests:
          raise ValueError("The type of Nominatim request is invalid. Please choose one of {{'search', 'reverse', 'lookup'}}")
  
      # prepare the Nominatim API URL and see if request already exists in the
      # cache
      url = 'https://nominatim.openstreetmap.org/{}'.format(type)
      prepared_url = requests.Request('GET', url, params=params).prepare().url
      cached_response_json = get_from_cache(prepared_url)
  
      if cached_response_json is not None:
          # found this request in the cache, just return it instead of making a
          # new HTTP call
          return cached_response_json
  
      else:
          # if this URL is not already in the cache, pause, then request it
          log('Pausing {:,.2f} seconds before making API GET request'.format(pause_duration))
          time.sleep(pause_duration)
          start_time = time.time()
          log('Requesting {} with timeout={}'.format(prepared_url, timeout))
          response = requests.get(url, params=params, timeout=timeout, headers=get_http_headers())
  
          # get the response size and the domain, log result
          size_kb = len(response.content) / 1000.
          domain = re.findall(r'//(?s)(.*?)/', url)[0]
          log('Downloaded {:,.1f}KB from {} in {:,.2f} seconds'.format(size_kb, domain, time.time()-start_time))
  
          try:
              response_json = response.json()
              save_to_cache(prepared_url, response_json)
          except Exception:
              #429 is 'too many requests' and 504 is 'gateway timeout' from server
              # overload - handle these errors by recursively calling
              # nominatim_request until we get a valid response
              if response.status_code in [429, 504]:
                  # pause for error_pause_duration seconds before re-trying request
                  log('Server at {} returned status code {} and no JSON data. Re-trying request in {:.2f} seconds.'.format(domain,
                                                                                                                           response.status_code,
                                                                                                                           error_pause_duration),
                                                                                                                           level=lg.WARNING)
                  time.sleep(error_pause_duration)
                  response_json = nominatim_request(params=params, pause_duration=pause_duration, timeout=timeout)
  
              # else, this was an unhandled status_code, throw an exception
              else:
                  log('Server at {} returned status code {} and no JSON data'.format(domain, response.status_code), level=lg.ERROR)
                  raise Exception('Server returned no JSON data.\n{} {}\n{}'.format(response, response.reason, response.text))
  
          return response_json