uri

README

go-whosonfirst-uri

Go package for working with URIs for Who's On First documents

Documentation

Example

Simple

import (
	"github.com/whosonfirst/go-whosonfirst-uri"
)

fname, _ := uri.Id2Fname(101736545)
rel_path, _ := uri.Id2RelPath(101736545)
abs_path, _ := uri.Id2AbsPath("/usr/local/data", 101736545)

Produces:

101736545.geojson
101/736/545/101736545.geojson
/usr/local/data/101/736/545/101736545.geojson

Fancy

import (
	"github.com/whosonfirst/go-whosonfirst-uri"
)

source := "mapzen"
function := "display"
extras := []string{ "1024" }

args := uri.NewAlternateURIArgs(source, function, extras...)

fname, _ := uri.Id2Fname(101736545, args)
rel_path, _ := uri.Id2RelPath(101736545, args)
abs_path, _ := uri.Id2AbsPath("/usr/local/data", 101736545, args)

Produces:

101736545-alt-mapzen-display-1024.geojson
101/736/545/101736545-alt-mapzen-display-1024.geojson
/usr/local/data/101/736/545/101736545-alt-mapzen-display-1024.geojson

The Long Version

Please read this: https://github.com/whosonfirst/whosonfirst-cookbook/blob/master/how_to/creating_alt_geometries.md

Tools

wof-uri-expand

Expand one or more IDs in to their URIs (relative or absolute).

./bin/wof-uri-expand -h
Usage of ./bin/wof-uri-expand:
  -root string
    	An optional (filesystem) root to prepend URIs with
  -stdin
    	Read IDs from STDIN

For example:

./bin/wof-uri-expand 1234556 46632
123/455/6/1234556.geojson
466/32/46632.geojson

Or:

./bin/wof-uri-expand -root /usr/local/data 1234556 46632
/usr/local/data/123/455/6/1234556.geojson
/usr/local/data/466/32/46632.geojson

Or:

cat ./test | ./bin/wof-uri-expand -stdin
487/463/636/453/487463636453.geojson
982/635/344/2/9826353442.geojson

See also

• https://github.com/whosonfirst/whosonfirst-cookbook/blob/master/how_to/creating_alt_geometries.md
• https://github.com/whosonfirst/py-mapzen-whosonfirst-uri

Documentation

Overview

package uri provides methods for parsing and constructing URIs for Who's On First documents.

Example (simple)

import (
	"github.com/whosonfirst/go-whosonfirst-uri"
)

fname, _ := uri.Id2Fname(101736545)
rel_path, _ := uri.Id2RelPath(101736545)
abs_path, _ := uri.Id2AbsPath("/usr/local/data", 101736545)

Produces:

101736545.geojson
101/736/545/101736545.geojson
/usr/local/data/101/736/545/101736545.geojson

Example (fancy)

import (
	"github.com/whosonfirst/go-whosonfirst-uri"
)

source := "mapzen"
function := "display"
extras := []string{ "1024" }

args := uri.NewAlternateURIArgs(source, function, extras...)

fname, _ := uri.Id2Fname(101736545, args)
rel_path, _ := uri.Id2RelPath(101736545, args)
abs_path, _ := uri.Id2AbsPath("/usr/local/data", 101736545, args)

Produces:

101736545-alt-mapzen-display-1024.geojson
101/736/545/101736545-alt-mapzen-display-1024.geojson
/usr/local/data/101/736/545/101736545-alt-mapzen-display-1024.geojson

For detailed description of the rules governing alternate geometries please consult: https://github.com/whosonfirst/whosonfirst-cookbook/blob/master/how_to/creating_alt_geometries.md

Index

• Constants
• func Id2AbsPath(root string, id int64, args ...*URIArgs) (string, error)
• func Id2Fname(id int64, args ...*URIArgs) (string, error)
• func Id2Path(id int64) (string, error)
• func Id2RelPath(id int64, args ...*URIArgs) (string, error)
• func IdFromPath(path string) (int64, error)
• func IsAltFile(path string) (bool, error)
• func IsAlternateGeometry(path string) (bool, error)
• func IsWOFFile(path string) (bool, error)
• func WhosOnFirstDataRepoFromPath(path string) (string, error)
• type AltGeom
  • func AltGeomFromPath(path string) (*AltGeom, error)
  • func (a *AltGeom) String() (string, error)
• type URIArgs
  • func NewAlternateURIArgs(source string, function string, extras ...string) *URIArgs
  • func NewAlternateURIArgsFromAltLabel(label string) (*URIArgs, error)
  • func NewDefaultURIArgs() *URIArgs
  • func ParseURI(path string) (int64, *URIArgs, error)

Constants

const URI_REGEXP string = `^(\d+)(?:\-alt(?:\-([a-zA-Z0-9_]+(?:\-[a-zA-Z0-9_]+(?:\-[a-zA-Z0-9_\-]+)?)?)))?(?:\.[^\.]+|\/)?$`

URI_REGEXP is the regular expression used to parse Who's On First URIs.

Functions

func Id2AbsPath

func Id2AbsPath(root string, id int64, args ...*URIArgs) (string, error)

Id2AbsPath parses a Who's On First ID and one or more URIArgs instances (in practice just one instance) in to a absolute URL for that ID. This method joins the `root` URL and the output of the `Id2RelPath` method.

func Id2Fname

func Id2Fname(id int64, args ...*URIArgs) (string, error)

Id2Fname parses a Who's On First ID and one or more URIArgs instances (in practice just one instance) in to a filename.

func Id2Path

func Id2Path(id int64) (string, error)

Id2Path parses a Who's On First ID in to directory tree that would contain that ID.

func Id2RelPath

func Id2RelPath(id int64, args ...*URIArgs) (string, error)

Id2RelPath parses a Who's On First ID and one or more URIArgs instances (in practice just one instance) in to a relative path for that ID. This method joins the output of the `Id2Path` and `Id2Fname` methods.

func IdFromPath

func IdFromPath(path string) (int64, error)

IdFromPath parses a path and return its unique Who's On First ID.

func IsAltFile

func IsAltFile(path string) (bool, error)

ISAltFile returns a boolean value indicating whether a path is a valid Who's On First URI for an "alternate" geometry.

func IsAlternateGeometry

func IsAlternateGeometry(path string) (bool, error)

IsAlternateGeometry returns a boolean value indicating whether 'path' is considered by an alternate geometry URI.

func IsWOFFile

func IsWOFFile(path string) (bool, error)

ISWOFFile returns a boolean value indicating whether a path is a valid Who's On First URI.

func WhosOnFirstDataRepoFromPath

func WhosOnFirstDataRepoFromPath(path string) (string, error)

RepoFromPath parses a path and if it is a valid whosonfirst-data Who's On First URI returns a GitHub repository name.

Types

type AltGeom

type AltGeom struct {
	// The source of the alternate geometry. This value is required and SHOULD match a corresponding entry in the whosonfirst/whosonfirst-sources repository.
	Source string `json:"source"`
	// The labeled function for the alternate geometry. This value MAY be a controlled value relative to `Source`.
	Function string `json:"function"`
	// A list of optional strings to append to the alternate geometry's URI.
	Extras []string `json:"extras,omitempty"`
	// A boolean value used to indicate whether the `Source` value has a corresponding entry in the whosonfirst/whosonfirst-sources repository.
	Strict bool `json:"strict"`
}

AltGeom is a struct containing details about an alternate geometry

func AltGeomFromPath

func AltGeomFromPath(path string) (*AltGeom, error)

AltGeomFromPath parses a path and returns its *AltGeom instance if it is a valid Who's On First "alternate" geometry URI.

func (*AltGeom) String

func (a *AltGeom) String() (string, error)

Return the string value for an alternate geometry.

type URIArgs

type URIArgs struct {
	// Boolean value indicating whether or not a URI is considered an alternate geometry
	IsAlternate bool `json:"is_alternate"`
	// And *AltGeom struct containing details about an alternate geometry
	AltGeom *AltGeom `json:"alternate_geometry"`
}

URIArgs is a struct indicating whether or not a URI is considered an alternate geometry and specific details if it is.

func NewAlternateURIArgs

func NewAlternateURIArgs(source string, function string, extras ...string) *URIArgs

Return a `URIArgs` struct representing an alternate geometry using the arguments defined in `source`, `function` and `extras`.

func NewAlternateURIArgsFromAltLabel

func NewAlternateURIArgsFromAltLabel(label string) (*URIArgs, error)

Return a `URIArgs` struct representing an alternate geometry derive from 'label' (which is expected to be the value of a valid "src:alt_label" or "src:geom_alt" property.

func NewDefaultURIArgs

func NewDefaultURIArgs() *URIArgs

Return a `URIArgs` struct whose IsAlternate flag is false.

func ParseURI

func ParseURI(path string) (int64, *URIArgs, error)

ParseURI will parse a Who's On First URI into its unique ID and any optional "alternate" geometry information.