search¶

This module allows developer to query zipcode with super clean API.

uszipcode.search.SORT_BY_DIST = 'dist'¶: a string for sort_by arguments. order the result by distance from a coordinates.

uszipcode.search.DEFAULT_LIMIT = 5¶: default number of results to return.

class uszipcode.search.SearchEngine(simple_or_comprehensive: uszipcode.search.SearchEngine.SimpleOrComprehensiveArgEnum = SimpleOrComprehensiveArgEnum.simple, db_file_path: Optional[str] = None, download_url: Optional[str] = None, engine: Optional[sqlalchemy.engine.base.Engine] = None)[source]¶

Zipcode Search Engine.

Parameters

simple_or_comprehensive (SearchEngine.SimpleOrComprehensiveArgEnum) – default SearchEngine.SimpleOrComprehensiveArgEnum, use the simple zipcode db. Rich Demographics, Real Estate, Employment, Education info are not available. if SearchEngine.SimpleOrComprehensiveArgEnum.comprehensive, use the rich info database.
db_file_path (str) – where you want to download the sqlite database to. This property allows you to customize where you want to store the data file locally. by default it is ${HOME}/.uszipcode/…
download_url (str) – where you want to download the sqlite database file from. This property allows you to upload the .sqlite file to your private file host and download from it. In case the default download url fail.
engine (Engine) – a sqlachemy engine object. It allows you to use any backend database instead of the default sqlite database.

Usage:

>>> search = SearchEngine()
>>> zipcode = search.by_zipcode("10001")

Context Manager:

>>> with SearchEngine() as search:
...     for zipcode in search.by_coordinates(lat, lng, radius):
...         # do what every you want

SearchEngine.query() provides mass options to customize your query.

SearchEngine.ses is a sqlalchemy.orm.Session object, you can use it for query. For example:

>>> from uszipcode import SearchEngine, SimpleZipcode, ComprehensiveZipcode
>>> search = SearchEngine()
>>> search.ses.scalar(SimpleZipcode).filter(SimpleZipcode.zipcode=="10001")

Note

SearchEngine is not multi-thread safe. You should create different instance for each thread.

class SimpleOrComprehensiveArgEnum(value)[source]¶: An enumeration.

close()[source]¶: close database connection.

property city_list¶: Return all available city name.

property state_list¶: Return all available state name.

find_state(state: str, best_match: bool = True, min_similarity: int = 70) → List[str][source]¶

Fuzzy search correct state.

Parameters: best_match – bool, when True, only the best matched state will be return. otherwise, will return all matching states.

find_city(city: str, state: Optional[str] = None, best_match: bool = True, min_similarity: int = 70) → List[str][source]¶

Fuzzy search correct city.

Parameters

city – city name.
state – search city in specified state.
best_match – bool, when True, only the best matched city will return. otherwise, will return all matching cities.

中文文档

如果给定了state, 则只在指定的state里的城市中寻找, 否则, 在全国所有的城市中寻找。

query(zipcode: Optional[Union[int, float]] = None, prefix: Optional[str] = None, pattern: Optional[str] = None, city: Optional[str] = None, state: Optional[str] = None, lat: Optional[Union[int, float]] = None, lng: Optional[Union[int, float]] = None, radius=None, population_lower: Optional[int] = None, population_upper: Optional[int] = None, population_density_lower: Optional[int] = None, population_density_upper: Optional[int] = None, land_area_in_sqmi_lower: Optional[int] = None, land_area_in_sqmi_upper: Optional[int] = None, water_area_in_sqmi_lower: Optional[int] = None, water_area_in_sqmi_upper: Optional[int] = None, housing_units_lower: Optional[int] = None, housing_units_upper: Optional[int] = None, occupied_housing_units_lower: Optional[int] = None, occupied_housing_units_upper: Optional[int] = None, median_home_value_lower: Optional[int] = None, median_home_value_upper: Optional[int] = None, median_household_income_lower: Optional[int] = None, median_household_income_upper: Optional[int] = None, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'zipcode', ascending: bool = True, returns: int = 5)[source]¶

Query zipcode the simple way.

Parameters

zipcode – int or str, find the exactly matched zipcode. Will be automatically zero padding to 5 digits
prefix – str, zipcode prefix.
pattern – str, zipcode wildcard.
city – str, city name.
state – str, state name, two letter abbr or state full name.
lat – latitude.
lng – longitude.
radius – number, only returns zipcodes within a specific circle.
population_lower –
population_upper –
population_density_lower –
population_density_upper –
land_area_in_sqmi_lower –
land_area_in_sqmi_upper –
water_area_in_sqmi_lower –
water_area_in_sqmi_upper –
housing_units_lower –
housing_units_upper –
occupied_housing_units_lower –
occupied_housing_units_upper –
median_home_value_lower –
median_home_value_upper –
median_household_income_lower –
median_household_income_upper –
zipcode_type – str or :class`~uszipcode.model.ZipcodeType` attribute. if None, allows to return any type of zipcode. if specified, only return specified zipcode type.
sort_by – str or Zipcode attribute, specified which field is used for sorting.
ascending – bool, True means ascending, False means descending.
returns – int or None, limit the number of result to returns.

Returns

list of SimpleZipcode or ComprehensiveZipcode.

by_zipcode(zipcode: Union[int, str], zero_padding: bool = True) → Optional[Union[uszipcode.model.SimpleZipcode, uszipcode.model.ComprehensiveZipcode]][source]¶

Search zipcode by exact 5 digits zipcode. No zero padding is needed.

Parameters

zipcode – int or str, the zipcode will be automatically zero padding to 5 digits.
zipcode_type – str or :class`~uszipcode.model.ZipcodeType` attribute. by default, it returns any zipcode type.
zero_padding – bool, toggle on and off automatic zero padding.

by_prefix(prefix: str, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'zipcode', ascending: bool = True, returns: int = 5)[source]¶

Search zipcode information by first N digits.

Returns multiple results.

by_pattern(pattern: str, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'zipcode', ascending: bool = True, returns: int = 5)[source]¶

Search zipcode by wildcard.

Returns multiple results.

by_city(city: str, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'zipcode', ascending: bool = True, returns: int = 5)[source]¶

Search zipcode information by fuzzy City name.

My engine use fuzzy match and guess what is the city you want.

by_state(state: str, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'zipcode', ascending: bool = True, returns: int = 5)[source]¶

Search zipcode information by fuzzy State name.

My engine use fuzzy match and guess what is the state you want.

by_city_and_state(city: str, state: str, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'zipcode', ascending: bool = True, returns: int = 5)[source]¶

Search zipcode information by fuzzy city and state name.

My engine use fuzzy match and guess what is the state you want.

by_coordinates(lat: Union[int, float], lng: Union[int, float], radius: Union[int, float] = 25.0, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'dist', ascending: bool = True, returns: int = 5)[source]¶

Search zipcode information near a coordinates on a map.

Returns multiple results.

Parameters

lat – center latitude.
lng – center longitude.
radius – only returns zipcode within X miles from lat, lng.

中文文档

计算出在中心坐标处, 每一经度和纬度分别代表多少miles.
以给定坐标为中心, 画出一个矩形, 长宽分别为半径的2倍多一点, 找到该

矩形内所有的Zipcode.

对这些Zipcode计算出他们的距离, 然后按照距离远近排序。距离超过我们

限定的半径的直接丢弃.

by_population(lower: int = - 1, upper: int = 2147483648, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'population', ascending: bool = False, returns: int = 5)[source]¶: Search zipcode information by population range.

by_population_density(lower: int = - 1, upper: int = 2147483648, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'population_density', ascending: bool = False, returns: int = 5)[source]¶

Search zipcode information by population density range.

population density is population per square miles on land

by_land_area_in_sqmi(lower: int = - 1, upper: int = 2147483648, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'land_area_in_sqmi', ascending: bool = False, returns: int = 5)[source]¶: Search zipcode information by land area / sq miles range.

by_water_area_in_sqmi(lower: int = - 1, upper: int = 2147483648, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'water_area_in_sqmi', ascending: bool = False, returns: int = 5)[source]¶: Search zipcode information by water area / sq miles range.

by_housing_units(lower: int = - 1, upper: int = 2147483648, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'housing_units', ascending: bool = False, returns: int = 5)[source]¶: Search zipcode information by house of units.

by_occupied_housing_units(lower: int = - 1, upper: int = 2147483648, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'occupied_housing_units', ascending: bool = False, returns: int = 5)[source]¶: Search zipcode information by occupied house of units.

by_median_home_value(lower: int = - 1, upper: int = 2147483648, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'median_home_value', ascending: bool = False, returns: int = 5)[source]¶: Search zipcode information by median home value.

by_median_household_income(lower: int = - 1, upper: int = 2147483648, zipcode_type: uszipcode.model.ZipcodeTypeEnum = ZipcodeTypeEnum.Standard, sort_by: str = 'median_household_income', ascending: bool = False, returns: int = 5)[source]¶: Search zipcode information by median household income.