ebird-api 3.4.1__tar.gz → 3.4.2__tar.gz

{ebird_api-3.4.1 → ebird_api-3.4.2}/CHANGELOG.md

@@ -8,6 +8,10 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 This project adheres to [PEP440](https://www.python.org/dev/peps/pep-0440/)
 and by implication, [Semantic Versioning](http://semver.org/).
 
+## [3.4.2] - 2025-04-05
+- Added a timeout so the client will raise an error if the connection
+  to eBird freezes
+
 ## [3.4.1] - 2025-02-12
 - Disallow lower case location codes
 

{ebird_api-3.4.1/src/ebird_api.egg-info → ebird_api-3.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: ebird-api
-Version: 3.4.1
+Version: 3.4.2
 Summary: Wrapper for accessing the eBird API
 Author-email: Project Babbler <projectbabbler@gmail.com>
 License: MIT License
@@ -27,6 +27,7 @@ Classifier: Topic :: Internet
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
+Dynamic: license-file
 
 [![Build Status](https://travis-ci.org/ProjectBabbler/ebird-api.svg?branch=master)](https://travis-ci.org/ProjectBabbler/ebird-api)
 [![PyPI version](https://badge.fury.io/py/ebird-api.svg)](https://badge.fury.io/py/ebird-api)
@@ -46,23 +47,23 @@ pip install ebird-api
 ## Usage
 
 Each of the functions map to a specific end-point in the API - with one or
-two exceptions where API calls are essentially identical. The functions can 
-be grouped into five activities: fetching observations, getting information 
-on hotspots, getting information on regions, getting lists of species and 
+two exceptions where API calls are essentially identical. The functions can
+be grouped into five activities: fetching observations, getting information
+on hotspots, getting information on regions, getting lists of species and
 getting statistics.
 
-All functions support arguments (with sensible defaults) for all the query 
-parameters supported by the eBird API. Check the docstring for each function 
-for more details. There you will also find a link to the documentation for 
+All functions support arguments (with sensible defaults) for all the query
+parameters supported by the eBird API. Check the docstring for each function
+for more details. There you will also find a link to the documentation for
 each end-point.
 
-To use the API you will need to register for an API key. All you need to do is 
-fill out this [form](https://ebird.org/api/keygen) and the API key is generated 
+To use the API you will need to register for an API key. All you need to do is
+fill out this [form](https://ebird.org/api/keygen) and the API key is generated
 automatically.
 
-NOTE: Use the API with some restraint. Data costs money so don't go downloading 
-all the checklists for the world or other excessive behaviour or your account will 
-get banned. If you have a project in mind get in touch with eBird and tell them 
+NOTE: Use the API with some restraint. Data costs money so don't go downloading
+all the checklists for the world or other excessive behaviour or your account will
+get banned. If you have a project in mind get in touch with eBird and tell them
 what you want to do - they will be interested to hear it.
 
 ### Observations
@@ -75,7 +76,7 @@ from ebird.api import get_observations
 # Always store secrets outside the code, so you don't accidentally
 # commit them. Environment variables are ideal for this.
 api_key = os.environ["EBIRD_API_KEY"]
-    
+
 # Get observations from Woodman Pond, Madison county, New York for the past week.
 this_week = get_observations(api_key, 'L227544', back=7)
 
@@ -89,8 +90,8 @@ state_records = get_observations(api_key, 'US-NY')
 national_records = get_observations(api_key, 'US')
 ```
 
-Any where you pass in single location or region you can also pass in a 
-list or a comma-separated string. You can specify up to 10 locations or 
+Any where you pass in single location or region you can also pass in a
+list or a comma-separated string. You can specify up to 10 locations or
 regions:
 
 ```python
@@ -111,8 +112,8 @@ counties = 'US-NY-103,US-NY-059,US-NY-81'
 records = get_observations(api_key, locations, hotspot=False, category='species')
 ```
 
-The common name for species can be returned in different languages by 
-specifying locale in the functions that return observations, checklists 
+The common name for species can be returned in different languages by
+specifying locale in the functions that return observations, checklists
 or taxonomy:
 
 ```python
@@ -126,7 +127,7 @@ records = get_observations(api_key, 'CA-QC', locale='fr')
 ```
 
 In addition to getting all the observations for a given location or in
-an area you can also get the latest observation of each species in a 
+an area you can also get the latest observation of each species in a
 geographical area - useful for finding the nearest place to see a given
 species:
 
@@ -137,23 +138,23 @@ from ebird.api import get_nearby_observations
 
 api_key = os.environ["EBIRD_API_KEY"]
 
-# Get the most recent sightings of all species seen in the last week within 
+# Get the most recent sightings of all species seen in the last week within
 # 10km of Point Reyes National Seashore.
 records = get_nearby_observations(api_key, 38.05, -122.94, dist=10, back=7)
 ```
 
-The calls to get_observations() and get_nearby_observation() return all the 
-available records. You can limit the set of records returned to only include 
-notable ones (locally or nationally rare species) or limit the records to 
+The calls to get_observations() and get_nearby_observation() return all the
+available records. You can limit the set of records returned to only include
+notable ones (locally or nationally rare species) or limit the records to
 a small number of species:
 
 ```python
 import os
 
 from ebird.api import (
-    get_notable_observations, 
+    get_notable_observations,
     get_nearby_notable,
-    get_species_observations, 
+    get_species_observations,
     get_nearby_species,
 )
 
@@ -175,14 +176,14 @@ nearby_species = get_nearby_species(api_key, 'barswa', 38.05, -122.94, back=10)
 For the more travel-minded you can also find out the nearest place to see a given species:
 
 ```python
-import os 
+import os
 
 from ebird.api import get_nearest_species
 
 api_key = os.environ["EBIRD_API_KEY"]
 
 # Where is the closest place to Cornell Lab of Ornithology to see
-# Tennessee Warbler. 
+# Tennessee Warbler.
 locations = get_nearest_species(api_key, 'tenwar', 42.48, -76.45)
 ```
 
@@ -192,7 +193,7 @@ Depending on what time of year you try this, you might have a long way to go.
 
 There are two functions for finding out what has been seen at a given location.
 First you can get the list of checklists for a given country, region or location
-using get_visits(). Each result returned has the unique identifier for the 
+using get_visits(). Each result returned has the unique identifier for the
 checklist. You can then call get_checklist() to get the list of observations.
 
 ```python
@@ -242,9 +243,9 @@ details = get_hotspot(api_key, 'L2313391')
 
 ### Regions
 
-eBird divides the world into countries, subnational1 regions (states) or 
-subnational2 regions (counties). You can use get_regions() to get the 
-list of sub-regions for a given region. For the approximate area covered 
+eBird divides the world into countries, subnational1 regions (states) or
+subnational2 regions (counties). You can use get_regions() to get the
+list of sub-regions for a given region. For the approximate area covered
 by a region use get_region().
 
 ```python
@@ -274,7 +275,7 @@ bounds = get_region(api_key, 'US-NY')
 
 You can get details of all the species, subspecies, forms
 etc. in the taxonomy used by eBird. It's the easiest way
-of getting the codes for each species or subspecies, 
+of getting the codes for each species or subspecies,
 e.g. horlar (Horned Lark), cangoo (Canada Goose), etc.,
 that are used in the other API calls.
 
@@ -307,7 +308,7 @@ versions = get_taxonomy_versions(api_key)
 You can also get some statistics from the eBird data. The most interesting
 is probably get_top_100() which returns the list of observers who have seen
 the most species or submitted the largest number of checklists. The list is
-just for a specific day so it is really only useful for "Big Days" when 
+just for a specific day so it is really only useful for "Big Days" when
 lots of people are out trying to get the greatest number of species.
 
 ```python
@@ -349,20 +350,36 @@ The client supports all the API functions.
 
 ## Formats
 
-Most of the eBird API calls return JSON. Some of the calls such as getting 
-the hotspots for a region or getting the taxonomy also support CSV. Since 
-converting JSON to CSV is simple this library is opinionated in that it 
+Most of the eBird API calls return JSON. Some of the calls such as getting
+the hotspots for a region or getting the taxonomy also support CSV. Since
+converting JSON to CSV is simple this library is opinionated in that it
 only returns JSON.
 
 ## Compatibility
 
-ebird-api works with currently supported versions of Python, 3.8+. However, 
-it is known to work with earlier versions, at least 3.5 - 3.7, without any 
+ebird-api works with currently supported versions of Python, 3.8+. However,
+it is known to work with earlier versions, at least 3.5 - 3.7, without any
 problems.
 
+## Troubleshooting
+
+Just occasionally (rarely in fact), the connection to eBird will freeze. The
+client will raise an error but if you use the API functions directly then your
+program will sit there forever. To fix this set a default timeout all connections
+using:
+
+```python
+import socket
+
+socket.setdefaulttimeout(30)
+```
+
+Thirty seconds is a reasonable figure, however you might change it if your
+internet connection is slow or the eBird servers are busy.
+
 ## Links
 
-Documentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro 
+Documentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro
 though it could do with a little love and attention.
 
 Available translations for species names: http://help.ebird.org/customer/portal/articles/1596582

{ebird_api-3.4.1 → ebird_api-3.4.2}/README.md

@@ -16,23 +16,23 @@ pip install ebird-api
 ## Usage
 
 Each of the functions map to a specific end-point in the API - with one or
-two exceptions where API calls are essentially identical. The functions can 
-be grouped into five activities: fetching observations, getting information 
-on hotspots, getting information on regions, getting lists of species and 
+two exceptions where API calls are essentially identical. The functions can
+be grouped into five activities: fetching observations, getting information
+on hotspots, getting information on regions, getting lists of species and
 getting statistics.
 
-All functions support arguments (with sensible defaults) for all the query 
-parameters supported by the eBird API. Check the docstring for each function 
-for more details. There you will also find a link to the documentation for 
+All functions support arguments (with sensible defaults) for all the query
+parameters supported by the eBird API. Check the docstring for each function
+for more details. There you will also find a link to the documentation for
 each end-point.
 
-To use the API you will need to register for an API key. All you need to do is 
-fill out this [form](https://ebird.org/api/keygen) and the API key is generated 
+To use the API you will need to register for an API key. All you need to do is
+fill out this [form](https://ebird.org/api/keygen) and the API key is generated
 automatically.
 
-NOTE: Use the API with some restraint. Data costs money so don't go downloading 
-all the checklists for the world or other excessive behaviour or your account will 
-get banned. If you have a project in mind get in touch with eBird and tell them 
+NOTE: Use the API with some restraint. Data costs money so don't go downloading
+all the checklists for the world or other excessive behaviour or your account will
+get banned. If you have a project in mind get in touch with eBird and tell them
 what you want to do - they will be interested to hear it.
 
 ### Observations
@@ -45,7 +45,7 @@ from ebird.api import get_observations
 # Always store secrets outside the code, so you don't accidentally
 # commit them. Environment variables are ideal for this.
 api_key = os.environ["EBIRD_API_KEY"]
-    
+
 # Get observations from Woodman Pond, Madison county, New York for the past week.
 this_week = get_observations(api_key, 'L227544', back=7)
 
@@ -59,8 +59,8 @@ state_records = get_observations(api_key, 'US-NY')
 national_records = get_observations(api_key, 'US')
 ```
 
-Any where you pass in single location or region you can also pass in a 
-list or a comma-separated string. You can specify up to 10 locations or 
+Any where you pass in single location or region you can also pass in a
+list or a comma-separated string. You can specify up to 10 locations or
 regions:
 
 ```python
@@ -81,8 +81,8 @@ counties = 'US-NY-103,US-NY-059,US-NY-81'
 records = get_observations(api_key, locations, hotspot=False, category='species')
 ```
 
-The common name for species can be returned in different languages by 
-specifying locale in the functions that return observations, checklists 
+The common name for species can be returned in different languages by
+specifying locale in the functions that return observations, checklists
 or taxonomy:
 
 ```python
@@ -96,7 +96,7 @@ records = get_observations(api_key, 'CA-QC', locale='fr')
 ```
 
 In addition to getting all the observations for a given location or in
-an area you can also get the latest observation of each species in a 
+an area you can also get the latest observation of each species in a
 geographical area - useful for finding the nearest place to see a given
 species:
 
@@ -107,23 +107,23 @@ from ebird.api import get_nearby_observations
 
 api_key = os.environ["EBIRD_API_KEY"]
 
-# Get the most recent sightings of all species seen in the last week within 
+# Get the most recent sightings of all species seen in the last week within
 # 10km of Point Reyes National Seashore.
 records = get_nearby_observations(api_key, 38.05, -122.94, dist=10, back=7)
 ```
 
-The calls to get_observations() and get_nearby_observation() return all the 
-available records. You can limit the set of records returned to only include 
-notable ones (locally or nationally rare species) or limit the records to 
+The calls to get_observations() and get_nearby_observation() return all the
+available records. You can limit the set of records returned to only include
+notable ones (locally or nationally rare species) or limit the records to
 a small number of species:
 
 ```python
 import os
 
 from ebird.api import (
-    get_notable_observations, 
+    get_notable_observations,
     get_nearby_notable,
-    get_species_observations, 
+    get_species_observations,
     get_nearby_species,
 )
 
@@ -145,14 +145,14 @@ nearby_species = get_nearby_species(api_key, 'barswa', 38.05, -122.94, back=10)
 For the more travel-minded you can also find out the nearest place to see a given species:
 
 ```python
-import os 
+import os
 
 from ebird.api import get_nearest_species
 
 api_key = os.environ["EBIRD_API_KEY"]
 
 # Where is the closest place to Cornell Lab of Ornithology to see
-# Tennessee Warbler. 
+# Tennessee Warbler.
 locations = get_nearest_species(api_key, 'tenwar', 42.48, -76.45)
 ```
 
@@ -162,7 +162,7 @@ Depending on what time of year you try this, you might have a long way to go.
 
 There are two functions for finding out what has been seen at a given location.
 First you can get the list of checklists for a given country, region or location
-using get_visits(). Each result returned has the unique identifier for the 
+using get_visits(). Each result returned has the unique identifier for the
 checklist. You can then call get_checklist() to get the list of observations.
 
 ```python
@@ -212,9 +212,9 @@ details = get_hotspot(api_key, 'L2313391')
 
 ### Regions
 
-eBird divides the world into countries, subnational1 regions (states) or 
-subnational2 regions (counties). You can use get_regions() to get the 
-list of sub-regions for a given region. For the approximate area covered 
+eBird divides the world into countries, subnational1 regions (states) or
+subnational2 regions (counties). You can use get_regions() to get the
+list of sub-regions for a given region. For the approximate area covered
 by a region use get_region().
 
 ```python
@@ -244,7 +244,7 @@ bounds = get_region(api_key, 'US-NY')
 
 You can get details of all the species, subspecies, forms
 etc. in the taxonomy used by eBird. It's the easiest way
-of getting the codes for each species or subspecies, 
+of getting the codes for each species or subspecies,
 e.g. horlar (Horned Lark), cangoo (Canada Goose), etc.,
 that are used in the other API calls.
 
@@ -277,7 +277,7 @@ versions = get_taxonomy_versions(api_key)
 You can also get some statistics from the eBird data. The most interesting
 is probably get_top_100() which returns the list of observers who have seen
 the most species or submitted the largest number of checklists. The list is
-just for a specific day so it is really only useful for "Big Days" when 
+just for a specific day so it is really only useful for "Big Days" when
 lots of people are out trying to get the greatest number of species.
 
 ```python
@@ -319,20 +319,36 @@ The client supports all the API functions.
 
 ## Formats
 
-Most of the eBird API calls return JSON. Some of the calls such as getting 
-the hotspots for a region or getting the taxonomy also support CSV. Since 
-converting JSON to CSV is simple this library is opinionated in that it 
+Most of the eBird API calls return JSON. Some of the calls such as getting
+the hotspots for a region or getting the taxonomy also support CSV. Since
+converting JSON to CSV is simple this library is opinionated in that it
 only returns JSON.
 
 ## Compatibility
 
-ebird-api works with currently supported versions of Python, 3.8+. However, 
-it is known to work with earlier versions, at least 3.5 - 3.7, without any 
+ebird-api works with currently supported versions of Python, 3.8+. However,
+it is known to work with earlier versions, at least 3.5 - 3.7, without any
 problems.
 
+## Troubleshooting
+
+Just occasionally (rarely in fact), the connection to eBird will freeze. The
+client will raise an error but if you use the API functions directly then your
+program will sit there forever. To fix this set a default timeout all connections
+using:
+
+```python
+import socket
+
+socket.setdefaulttimeout(30)
+```
+
+Thirty seconds is a reasonable figure, however you might change it if your
+internet connection is slow or the eBird servers are busy.
+
 ## Links
 
-Documentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro 
+Documentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro
 though it could do with a little love and attention.
 
 Available translations for species names: http://help.ebird.org/customer/portal/articles/1596582

{ebird_api-3.4.1 → ebird_api-3.4.2}/pyproject.toml

@@ -30,7 +30,7 @@ license = {text = "MIT License"}
 name = "ebird-api"
 readme = "README.md"
 requires-python = ">= 3.8"
-version = "3.4.1"
+version = "3.4.2"
 
 [project.urls]
 Repository = "https://github.com/ProjectBabbler/ebird-api.git"
@@ -38,7 +38,7 @@ Issues = "https://github.com/ProjectBabbler/ebird-api/issues"
 Changelog = "https://github.com/ProjectBabbler/ebird-api/blob/master/CHANGELOG.md"
 
 [tool.bumpversion]
-current_version = "3.4.1"
+current_version = "3.4.2"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 ignore_missing_version = false

{ebird_api-3.4.1 → ebird_api-3.4.2}/src/ebird/api/__init__.py

@@ -2,7 +2,7 @@
 
 """A set of wrapper functions for accessing the eBird API."""
 
-__version__ = "3.4.1"
+__version__ = "3.4.2"
 
 from ebird.api.checklists import get_checklist, get_visits
 from ebird.api.client import Client

{ebird_api-3.4.1 → ebird_api-3.4.2}/src/ebird/api/client.py

@@ -2,6 +2,8 @@
 
 """Classes for simplifying calls to the eBird API."""
 
+import socket
+
 from ebird.api import (
     checklists,
     constants,
@@ -41,6 +43,7 @@ class Client:
         self.hotspot = False
         self.provisional = True
         self.sort = "date"
+        socket.setdefaulttimeout(constants.DEFAULT_TIMEOUT)
 
     def get_observations(self, area):
         """Get recent observations (up to 30 days ago) for a region or location.

{ebird_api-3.4.1 → ebird_api-3.4.2}/src/ebird/api/constants.py

@@ -101,3 +101,8 @@ SPECIES_SORT = ["date", "species"]
 REGION_TYPES = ["country", "subnational1", "subnational2"]
 
 TOP_100_RANK = ["spp", "cl"]
+
+# Just occasionally the connection to eBird freezes. The timeout
+# will raise an error which is preferable to the sitting there
+# waiting for something to happen, when it will not.
+DEFAULT_TIMEOUT = 30

{ebird_api-3.4.1 → ebird_api-3.4.2/src/ebird_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: ebird-api
-Version: 3.4.1
+Version: 3.4.2
 Summary: Wrapper for accessing the eBird API
 Author-email: Project Babbler <projectbabbler@gmail.com>
 License: MIT License
@@ -27,6 +27,7 @@ Classifier: Topic :: Internet
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
+Dynamic: license-file
 
 [![Build Status](https://travis-ci.org/ProjectBabbler/ebird-api.svg?branch=master)](https://travis-ci.org/ProjectBabbler/ebird-api)
 [![PyPI version](https://badge.fury.io/py/ebird-api.svg)](https://badge.fury.io/py/ebird-api)
@@ -46,23 +47,23 @@ pip install ebird-api
 ## Usage
 
 Each of the functions map to a specific end-point in the API - with one or
-two exceptions where API calls are essentially identical. The functions can 
-be grouped into five activities: fetching observations, getting information 
-on hotspots, getting information on regions, getting lists of species and 
+two exceptions where API calls are essentially identical. The functions can
+be grouped into five activities: fetching observations, getting information
+on hotspots, getting information on regions, getting lists of species and
 getting statistics.
 
-All functions support arguments (with sensible defaults) for all the query 
-parameters supported by the eBird API. Check the docstring for each function 
-for more details. There you will also find a link to the documentation for 
+All functions support arguments (with sensible defaults) for all the query
+parameters supported by the eBird API. Check the docstring for each function
+for more details. There you will also find a link to the documentation for
 each end-point.
 
-To use the API you will need to register for an API key. All you need to do is 
-fill out this [form](https://ebird.org/api/keygen) and the API key is generated 
+To use the API you will need to register for an API key. All you need to do is
+fill out this [form](https://ebird.org/api/keygen) and the API key is generated
 automatically.
 
-NOTE: Use the API with some restraint. Data costs money so don't go downloading 
-all the checklists for the world or other excessive behaviour or your account will 
-get banned. If you have a project in mind get in touch with eBird and tell them 
+NOTE: Use the API with some restraint. Data costs money so don't go downloading
+all the checklists for the world or other excessive behaviour or your account will
+get banned. If you have a project in mind get in touch with eBird and tell them
 what you want to do - they will be interested to hear it.
 
 ### Observations
@@ -75,7 +76,7 @@ from ebird.api import get_observations
 # Always store secrets outside the code, so you don't accidentally
 # commit them. Environment variables are ideal for this.
 api_key = os.environ["EBIRD_API_KEY"]
-    
+
 # Get observations from Woodman Pond, Madison county, New York for the past week.
 this_week = get_observations(api_key, 'L227544', back=7)
 
@@ -89,8 +90,8 @@ state_records = get_observations(api_key, 'US-NY')
 national_records = get_observations(api_key, 'US')
 ```
 
-Any where you pass in single location or region you can also pass in a 
-list or a comma-separated string. You can specify up to 10 locations or 
+Any where you pass in single location or region you can also pass in a
+list or a comma-separated string. You can specify up to 10 locations or
 regions:
 
 ```python
@@ -111,8 +112,8 @@ counties = 'US-NY-103,US-NY-059,US-NY-81'
 records = get_observations(api_key, locations, hotspot=False, category='species')
 ```
 
-The common name for species can be returned in different languages by 
-specifying locale in the functions that return observations, checklists 
+The common name for species can be returned in different languages by
+specifying locale in the functions that return observations, checklists
 or taxonomy:
 
 ```python
@@ -126,7 +127,7 @@ records = get_observations(api_key, 'CA-QC', locale='fr')
 ```
 
 In addition to getting all the observations for a given location or in
-an area you can also get the latest observation of each species in a 
+an area you can also get the latest observation of each species in a
 geographical area - useful for finding the nearest place to see a given
 species:
 
@@ -137,23 +138,23 @@ from ebird.api import get_nearby_observations
 
 api_key = os.environ["EBIRD_API_KEY"]
 
-# Get the most recent sightings of all species seen in the last week within 
+# Get the most recent sightings of all species seen in the last week within
 # 10km of Point Reyes National Seashore.
 records = get_nearby_observations(api_key, 38.05, -122.94, dist=10, back=7)
 ```
 
-The calls to get_observations() and get_nearby_observation() return all the 
-available records. You can limit the set of records returned to only include 
-notable ones (locally or nationally rare species) or limit the records to 
+The calls to get_observations() and get_nearby_observation() return all the
+available records. You can limit the set of records returned to only include
+notable ones (locally or nationally rare species) or limit the records to
 a small number of species:
 
 ```python
 import os
 
 from ebird.api import (
-    get_notable_observations, 
+    get_notable_observations,
     get_nearby_notable,
-    get_species_observations, 
+    get_species_observations,
     get_nearby_species,
 )
 
@@ -175,14 +176,14 @@ nearby_species = get_nearby_species(api_key, 'barswa', 38.05, -122.94, back=10)
 For the more travel-minded you can also find out the nearest place to see a given species:
 
 ```python
-import os 
+import os
 
 from ebird.api import get_nearest_species
 
 api_key = os.environ["EBIRD_API_KEY"]
 
 # Where is the closest place to Cornell Lab of Ornithology to see
-# Tennessee Warbler. 
+# Tennessee Warbler.
 locations = get_nearest_species(api_key, 'tenwar', 42.48, -76.45)
 ```
 
@@ -192,7 +193,7 @@ Depending on what time of year you try this, you might have a long way to go.
 
 There are two functions for finding out what has been seen at a given location.
 First you can get the list of checklists for a given country, region or location
-using get_visits(). Each result returned has the unique identifier for the 
+using get_visits(). Each result returned has the unique identifier for the
 checklist. You can then call get_checklist() to get the list of observations.
 
 ```python
@@ -242,9 +243,9 @@ details = get_hotspot(api_key, 'L2313391')
 
 ### Regions
 
-eBird divides the world into countries, subnational1 regions (states) or 
-subnational2 regions (counties). You can use get_regions() to get the 
-list of sub-regions for a given region. For the approximate area covered 
+eBird divides the world into countries, subnational1 regions (states) or
+subnational2 regions (counties). You can use get_regions() to get the
+list of sub-regions for a given region. For the approximate area covered
 by a region use get_region().
 
 ```python
@@ -274,7 +275,7 @@ bounds = get_region(api_key, 'US-NY')
 
 You can get details of all the species, subspecies, forms
 etc. in the taxonomy used by eBird. It's the easiest way
-of getting the codes for each species or subspecies, 
+of getting the codes for each species or subspecies,
 e.g. horlar (Horned Lark), cangoo (Canada Goose), etc.,
 that are used in the other API calls.
 
@@ -307,7 +308,7 @@ versions = get_taxonomy_versions(api_key)
 You can also get some statistics from the eBird data. The most interesting
 is probably get_top_100() which returns the list of observers who have seen
 the most species or submitted the largest number of checklists. The list is
-just for a specific day so it is really only useful for "Big Days" when 
+just for a specific day so it is really only useful for "Big Days" when
 lots of people are out trying to get the greatest number of species.
 
 ```python
@@ -349,20 +350,36 @@ The client supports all the API functions.
 
 ## Formats
 
-Most of the eBird API calls return JSON. Some of the calls such as getting 
-the hotspots for a region or getting the taxonomy also support CSV. Since 
-converting JSON to CSV is simple this library is opinionated in that it 
+Most of the eBird API calls return JSON. Some of the calls such as getting
+the hotspots for a region or getting the taxonomy also support CSV. Since
+converting JSON to CSV is simple this library is opinionated in that it
 only returns JSON.
 
 ## Compatibility
 
-ebird-api works with currently supported versions of Python, 3.8+. However, 
-it is known to work with earlier versions, at least 3.5 - 3.7, without any 
+ebird-api works with currently supported versions of Python, 3.8+. However,
+it is known to work with earlier versions, at least 3.5 - 3.7, without any
 problems.
 
+## Troubleshooting
+
+Just occasionally (rarely in fact), the connection to eBird will freeze. The
+client will raise an error but if you use the API functions directly then your
+program will sit there forever. To fix this set a default timeout all connections
+using:
+
+```python
+import socket
+
+socket.setdefaulttimeout(30)
+```
+
+Thirty seconds is a reasonable figure, however you might change it if your
+internet connection is slow or the eBird servers are busy.
+
 ## Links
 
-Documentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro 
+Documentation for the eBird API: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest#intro
 though it could do with a little love and attention.
 
 Available translations for species names: http://help.ebird.org/customer/portal/articles/1596582