geozip

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:

• CountryCode
• PostalCode
• PlaceName
• AdminName1
• AdminCode1
• AdminName2
• AdminCode2
• AdminName3
• AdminCode3
• Latitude
• Longitude
• Accuracy

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

• Variables
• type Entry
  • func FetchCountry(cc, etag string) (entries []Entry, modified bool, newEtag string, err error)
• type Field

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.

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

func FetchCountry(cc, etag string) (entries []Entry, modified bool, newEtag string, err error)

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
)