README
¶
Geozip
Overview
The geozip package is designed for fetching and parsing postal code data, specifically from the GeoNames geographical database (https://www.geonames.org/).
It offers a straightforward interface to download postal code data for various countries and parse them into a structured Go data type.
Features
- Download postal code data by country from the GeoNames database.
- Utilizes HTTP ETag caching to minimize data transfer.
- Parses the downloaded data into a structured format for easy use in Go applications.
Installation
To use the geozip package in your Go project, simply execute the following command:
go get github.com/ngrash/geozip
Usage
Fetching Postal Code Data
To fetch postal code data for a specific country, use the FetchCountry function. This function also supports ETag caching to minimize unnecessary data transfers.
Example:
package main
import "github.com/ngrash/geozip"
func main() {
var previousEtag string
entries, modified, newEtag, err := geozip.FetchCountry("US", previousEtag)
if err != nil {
// Handle error
}
if modified {
// Process new entries
// Save newEtag for future requests
}
}
Fields in Postal Code Entry
Each postal code entry (Entry type) is an array of 12 strings, representing different data fields:
CountryCodePostalCodePlaceNameAdminName1AdminCode1AdminName2AdminCode2AdminName3AdminCode3LatitudeLongitudeAccuracy
Contributing
Contributions to the geozip package are welcome. Please feel free to submit pull requests or open issues for bugs, feature requests, license problems or documentation improvements.
License
This project is licensed under the MIT License.
The data downloaded from GeoNames.org is licensed under Creative Commons Attribution 4.0 License. This includes the ZIP file in the test_data directory as well as derived snippets used in the tests. Postal code databases for some countries may come with additional licenses. See GeoName's readme.txt for details.
Documentation
¶
Overview ¶
Package geozip provides functionality specifically for downloading and parsing postal code data from the GeoNames geographical database (https://www.geonames.org/).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var HTTPClient http.Client
HTTPClient is a global http.Client instance used for making HTTP requests. This can be replaced or configured as needed to change the default HTTP behavior.
Functions ¶
This section is empty.
Types ¶
type Entry ¶
type Entry [12]string
Entry represents a single postal code entry. It is an array of 12 strings, each representing a specific field of data.
func FetchCountry ¶
FetchCountry fetches postal code entries for a specific country code from the GeoNames database. It leverages the HTTP ETag mechanism to minimize data transfer for unchanged postal code data.
The function takes two arguments:
cc: The country code for which postal code data is to be fetched. etag: An ETag value from a previous request to this function.
If the data for the given country code has not changed since the last request with the provided ETag, the function returns with 'modified' set to false, and no new data is fetched.
If the data has changed, or if this is the first request (indicated by an empty etag), the function fetches the updated data, sets 'modified' to true, and returns the new data along with the new ETag.
Example usage:
entries, modified, newEtag, err := FetchCountry("US", previousEtag)
if err != nil {
// Handle error
}
if modified {
// Process new entries
// Save newEtag for future requests
}
See https://download.geonames.org/export/zip/ for a list of available countries.
type Field ¶
type Field int
Field represents a specific field in a postal code entry.
const ( // CountryCode is the index for the country code in a postal code entry. CountryCode Field = iota // PostalCode is the index for the postal code in a postal code entry. PostalCode // PlaceName is the index for the place name in a postal code entry. PlaceName // AdminName1 is the index for the first level of administrative division name in a postal code entry. AdminName1 // AdminCode1 is the index for the first level of administrative division code in a postal code entry. AdminCode1 // AdminName2 is the index for the second level of administrative division name in a postal code entry. AdminName2 // AdminCode2 is the index for the second level of administrative division code in a postal code entry. AdminCode2 // AdminName3 is the index for the third level of administrative division name in a postal code entry. AdminName3 // AdminCode3 is the index for the third level of administrative division code in a postal code entry. AdminCode3 // Latitude is the index for the latitude in a postal code entry. Latitude // Longitude is the index for the longitude in a postal code entry. Longitude // Accuracy is the index for the accuracy in a postal code entry. Accuracy )
Source Files