Exemple #1
0
def get_sites(sites=None, state_code=None, huc=None, bounding_box=None, 
        county_code=None, parameter_code=None, site_type=None, service=None, 
        input_file=None, **kwargs):
    """Fetches site information from USGS services. See the `USGS Site Service`_
    documentation for a detailed description of options. For convenience, major
    options have been included with pythonic names. Options that are not listed 
    below may be provided as extra kwargs (i.e. keyword='argument') and will be 
    passed along with the web services request. These extra keywords must match 
    the USGS names exactly. The `USGS Site Service`_ website describes available
    keyword names and argument formats. 

    .. USGS Site Service:http://waterservices.usgs.gov/rest/Site-Service.html

    .. note::
        Only the options listed below have been tested and you may have mixed 
        results retrieving data with extra options specified. Currently ulmo 
        requests and parses data in the waterml format. Some options are not 
        available in this format.

    Parameters
    ==========
    service : {``None``, 'instantaneous', 'iv', 'daily', 'dv'}
        The service to use, either "instantaneous", "daily", or ``None``
        (default).  If set to ``None``, then both services are used.  The
        abbreviations "iv" and "dv" can be used for "instantaneous" and "daily",
        respectively.
    input_file: ``None``, file path or file object
        If ``None`` (default), then the NWIS web services will be queried, but
        if a file is passed then this file will be used instead of requesting
        data from the NWIS web services.

    Major Filters (At least one filter must be specified)
    -----------------------------------------------------
        sites : str, iterable of strings or ``None``
            The site(s) to use; lists will be joined by a ','. 
        state_code : str or ``None``
            Two-letter state code used in stateCd parameter.
        county_code : str, iterable of strings or ``None``
            The 5 digit FIPS county code(s) used in the countyCd parameter; lists 
            will be joined by a ','.
        huc : str, iterable of strings or ``None``
            The hydrologic unit code(s) to use; lists will be joined by a ','.
        bounding_box : str, iterable of strings or ``None``
            This bounding box used in the bBox parameter. The format is westernmost 
            longitude, southernmost latitude, easternmost longitude, northernmost 
            latitude; lists will be joined by a ','.

    Optional Filters Provided
    -------------------------
        parameter_code : str, iterable of strings or ``None``
            Parameter code(s) that will be passed as the parameterCd parameter; lists will be joined by a ','.   
            This parameter represents the following usgs website input: Sites serving parameter codes
        site_types : str, iterable of strings or ``None``
            The type(s) of site used in siteType parameter; lists will be joined by a ','.


    Returns
    -------
    sites_dict : dict
        a python dict with site codes mapped to site information
    """
    
    if input_file is None:
        # Checking to see if the correct amount of major filters are being used.
        # The NWIS site requires only one major filter to be used at a time.
        major_filters = [sites, state_code, huc, bounding_box, county_code]

        if not any(major_filters):
            error_msg = (
                    '*At least one* of the following major filters must be supplied: '
                    'sites, state_code, huc, bounding_box, country_code.'
                )
            raise ValueError(error_msg)  

        if len([_f for _f in major_filters if _f]) > 1:
            error_msg = (
                    '*Only one* of the following major filters can be supplied:'
                    'sites, state_code, huc, bounding_box, country_code.'
                )
            raise ValueError(error_msg)    
        
        url_params = {'format': 'waterml'}

        if state_code:
            url_params['stateCd'] = state_code

        if sites:
            url_params['sites'] = _as_str(sites)

        if huc:
            url_params['hucs'] = _as_str(huc)

        if bounding_box:
            url_params['bBox'] = _as_str(bounding_box)

        if county_code:
            url_params['countyCd'] = _as_str(county_code)

        if site_type:
            url_params['siteType'] = _as_str(site_type)

        if parameter_code:
            url_params['parameterCd'] = _as_str(parameter_code)

        url_params.update(kwargs)

        if not service:
            return_sites = {}
            for service in ['daily', 'instantaneous']:
                new_sites = get_sites(sites=sites, state_code=state_code, huc=huc, 
                                bounding_box=bounding_box, county_code=county_code, parameter_code=parameter_code, 
                                site_type=site_type, service=service, input_file=input_file, **kwargs)
                return_sites.update(new_sites)
            return return_sites

        url = _get_service_url(service)
        log.info('making request for sites: %s' % url)
        req = requests.get(url, params=url_params)
        log.info("processing data from request: %s" % req.request.url)
        req.raise_for_status()        
        input_file = io.BytesIO(util.to_bytes(req.content))

    with _open_input_file(input_file) as content_io:
        return_sites = wml.parse_site_infos(content_io)

    return_sites = dict([
        (code, _extract_site_properties(site))
        for code, site in return_sites.items()
    ])

    return return_sites
Exemple #2
0
def get_sites(sites=None, state_code=None, site_type=None, service=None,
        input_file=None):
    """Fetches site information from USGS services. See the USGS waterservices
    documentation for options.


    Parameters
    ----------
    sites : str, iterable of strings or ``None``
        The site to use or list of sites to use; lists will be joined by a ','.
    state_code : str or ``None``
        Two-letter state code used in stateCd parameter.
    site_type : str or ``None``
        Type of site used in siteType parameter.
    service : {``None``, 'instantaneous', 'iv', 'daily', 'dv'}
        The service to use, either "instantaneous", "daily", or ``None``
        (default).  If set to ``None``, then both services are used.  The
        abbreviations "iv" and "dv" can be used for "instantaneous" and "daily",
        respectively.
    input_file: ``None``, file path or file object
        If ``None`` (default), then the NWIS web services will be queried, but
        if a file is passed then this file will be used instead of requesting
        data from the NWIS web services.

    Returns
    -------
    sites_dict : dict
        a python dict with site codes mapped to site information
    """
    url_params = {'format': 'waterml'}

    if state_code:
        url_params['stateCd'] = state_code

    if sites:
        if isinstance(sites, basestring):
            url_params['sites'] = sites
        else:
            url_params['sites'] = ','.join(sites)

    if site_type:
        url_params['siteType'] = site_type

    if input_file is None:
        if not service:
            return_sites = get_sites(sites=sites, state_code=state_code,
                    site_type=site_type, service="daily", input_file=input_file)
            instantaneous_sites = get_sites(sites=sites, state_code=state_code,
                site_type=site_type, service="instantaneous", input_file=input_file)
            return_sites.update(instantaneous_sites)
            return return_sites

        url = _get_service_url(service)
        log.info('making request for sites: %s' % url)
        req = requests.get(url, params=url_params)
        log.info("processing data from request: %s" % req.request.url)
        input_file = StringIO.StringIO(str(req.content))

    with _open_input_file(input_file) as content_io:
        return_sites = wml.parse_site_infos(content_io)

    return_sites = dict([
        (code, _extract_site_properties(site))
        for code, site in return_sites.iteritems()
    ])

    return return_sites
Exemple #3
0
def get_sites(sites=None,
              state_code=None,
              huc=None,
              bounding_box=None,
              county_code=None,
              parameter_code=None,
              site_type=None,
              service=None,
              input_file=None,
              **kwargs):
    """Fetches site information from USGS services. See the `USGS Site Service`_
    documentation for a detailed description of options. For convenience, major
    options have been included with pythonic names. Options that are not listed 
    below may be provided as extra kwargs (i.e. keyword='argument') and will be 
    passed along with the web services request. These extra keywords must match 
    the USGS names exactly. The `USGS Site Service`_ website describes available
    keyword names and argument formats. 

    .. USGS Site Service:http://waterservices.usgs.gov/rest/Site-Service.html

    .. note::
        Only the options listed below have been tested and you may have mixed 
        results retrieving data with extra options specified. Currently ulmo 
        requests and parses data in the waterml format. Some options are not 
        available in this format.

    Parameters
    ==========
    service : {``None``, 'instantaneous', 'iv', 'daily', 'dv'}
        The service to use, either "instantaneous", "daily", or ``None``
        (default).  If set to ``None``, then both services are used.  The
        abbreviations "iv" and "dv" can be used for "instantaneous" and "daily",
        respectively.
    input_file: ``None``, file path or file object
        If ``None`` (default), then the NWIS web services will be queried, but
        if a file is passed then this file will be used instead of requesting
        data from the NWIS web services.

    Major Filters (At least one filter must be specified)
    -----------------------------------------------------
        sites : str, iterable of strings or ``None``
            The site(s) to use; lists will be joined by a ','. 
        state_code : str or ``None``
            Two-letter state code used in stateCd parameter.
        county_code : str, iterable of strings or ``None``
            The 5 digit FIPS county code(s) used in the countyCd parameter; lists 
            will be joined by a ','.
        huc : str, iterable of strings or ``None``
            The hydrologic unit code(s) to use; lists will be joined by a ','.
        bounding_box : str, iterable of strings or ``None``
            This bounding box used in the bBox parameter. The format is westernmost 
            longitude, southernmost latitude, easternmost longitude, northernmost 
            latitude; lists will be joined by a ','.

    Optional Filters Provided
    -------------------------
        parameter_code : str, iterable of strings or ``None``
            Parameter code(s) that will be passed as the parameterCd parameter; lists will be joined by a ','.   
            This parameter represents the following usgs website input: Sites serving parameter codes
        site_types : str, iterable of strings or ``None``
            The type(s) of site used in siteType parameter; lists will be joined by a ','.


    Returns
    -------
    sites_dict : dict
        a python dict with site codes mapped to site information
    """

    if input_file is None:
        # Checking to see if the correct amount of major filters are being used.
        # The NWIS site requires only one major filter to be used at a time.
        major_filters = [sites, state_code, huc, bounding_box, county_code]

        if not any(major_filters):
            error_msg = (
                '*At least one* of the following major filters must be supplied: '
                'sites, state_code, huc, bounding_box, country_code.')
            raise ValueError(error_msg)

        if len([_f for _f in major_filters if _f]) > 1:
            error_msg = (
                '*Only one* of the following major filters can be supplied:'
                'sites, state_code, huc, bounding_box, country_code.')
            raise ValueError(error_msg)

        url_params = {'format': 'waterml'}

        if state_code:
            url_params['stateCd'] = state_code

        if sites:
            url_params['sites'] = _as_str(sites)

        if huc:
            url_params['hucs'] = _as_str(huc)

        if bounding_box:
            url_params['bBox'] = _as_str(bounding_box)

        if county_code:
            url_params['countyCd'] = _as_str(county_code)

        if site_type:
            url_params['siteType'] = _as_str(site_type)

        if parameter_code:
            url_params['parameterCd'] = _as_str(parameter_code)

        url_params.update(kwargs)

        if not service:
            return_sites = {}
            for service in ['daily', 'instantaneous']:
                new_sites = get_sites(sites=sites,
                                      state_code=state_code,
                                      huc=huc,
                                      bounding_box=bounding_box,
                                      county_code=county_code,
                                      parameter_code=parameter_code,
                                      site_type=site_type,
                                      service=service,
                                      input_file=input_file,
                                      **kwargs)
                return_sites.update(new_sites)
            return return_sites

        url = _get_service_url(service)
        log.info('making request for sites: %s' % url)
        req = requests.get(url, params=url_params)
        log.info("processing data from request: %s" % req.request.url)
        req.raise_for_status()
        input_file = io.BytesIO(util.to_bytes(req.content))

    with _open_input_file(input_file) as content_io:
        return_sites = wml.parse_site_infos(content_io)

    return_sites = dict([(code, _extract_site_properties(site))
                         for code, site in return_sites.items()])

    return return_sites