The cl-geocode Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-geocode Reference Manual

This is the cl-geocode Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 08:04:41 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-geocode: a geocoding API for Common Lisp

Geocoding is the process of finding associated geographic coordinates (expressed as latitude and longitude) from other geographic data, such as street addresses, or zip codes (postal codes).

Reverse geocoding is the opposite: finding an associated textual location such as a street address, from geographic coordinates.

This API does both.

cl-geocode is loaded via ASDF and the file cl-geocode.asd.

Examples

cl-user(12): (asdf:load-system :cl-geocode)
...
cl-user(13): (use-package :cl-geocode)
t
cl-user(14): (setq cl-geocode:*default-key* "...")
"..."
cl-user(15): (place-to-location "Berkeley, CA")
#<location 37.871593,-122.27274>
cl-user(16): (location-to-place *)
"Berkeley, California"
cl-user(17): (location-to-place
	    (place-to-location
	     "2629 College Ave, Berkeley, CA"))
"Berkeley, California"
cl-user(18): (place-to-location "2629 College Ave, Berkeley, CA")
#<location 37.862926,-122.25329>
cl-user(19): (distance-between
	    (place-to-location "Boulder, CO")
	    (place-to-location "Piedmont, CA"))
923.7708985128291d0
cl-user(20): (distance-between
	    (place-to-location "Lake Wylie, SC")
	    (place-to-location "Piedmont, CA"))
2280.312157508608d0
cl-user(21): 

Examples of the lower-level parts of the API:

cl-user(4): (setq location1
	  (make-location :latitude 38.005 :longitude -121.804726))
#<location 38.005,-121.804726>
cl-user(5): (setq location2
	  (make-location :latitude 37.824444 :longitude -122.23055))
#<location 37.824444,-122.23055>
cl-user(6): (distance-between location1 location2)
26.379927592149343d0
cl-user(7): (distance-between location1 location2 :unit :kilometers)
42.46016888326334d0
cl-user(8): 

;; The following examples inspired by
;;   http://nationalatlas.gov/articles/mapping/a_latlong.html#four

;; A degree of latitude should be approximately 69 miles:
cl-user(8): (distance-between
	 (make-location :latitude 38.0 :longitude -121.0)
	 (make-location :latitude 37.0 :longitude -121.0))
69.16739825655358d0
cl-user(9): 

;; A degree of longitude (at the equator) is also approximately 69
;; miles:
cl-user(9): (distance-between
	 (make-location :latitude 0.0 :longitude -121.0)
	 (make-location :latitude 0.0 :longitude -122.0))
69.16739825652837d0
cl-user(10): 

;; But as you move north or south the size gradually decreases to zero as
;; the meridians converge at the poles:

cl-user(10): (distance-between
	  (make-location :latitude 37.0 :longitude -121.0)
	  (make-location :latitude 37.0 :longitude -122.0))
55.23928644738535d0
cl-user(11): (distance-between
	  (make-location :latitude 50.0 :longitude -121.0)
	  (make-location :latitude 50.0 :longitude -122.0))
44.459615443471485d0
cl-user(12): (distance-between
	  (make-location :latitude 80.0 :longitude -121.0)
	  (make-location :latitude 80.0 :longitude -122.0))
12.010644812832272d0
cl-user(13): (distance-between
	  (make-location :latitude 90.0 :longitude -121.0)
	  (make-location :latitude 90.0 :longitude -122.0))
0.0d0
cl-user(14): 

Sometimes it is nice to see if a location is near another:

cl-user(15): (location-near-p
	  (make-location :latitude 37.824444 :longitude -122.23055)
	  (make-location :latitude 38.005 :longitude -121.804726)
	  1.0)
t
cl-user(16): (location-near-p
	  (make-location :latitude 37.824444 :longitude -122.23055)
	  (make-location :latitude 38.005 :longitude -121.804726)
	  0.5)
t
cl-user(17): (location-near-p
	  (make-location :latitude 37.824444 :longitude -122.23055)
	  (make-location :latitude 38.005 :longitude -121.804726)
	  0.1)
nil
cl-user(18): 

The complete API

Types

A location is a structure containing a latitude and longitude. The accessors are:

location-latitude
location-longitude

and the constructor is

make-location

Variables

*default-key*

The value of this is a string representing your Google Maps API key. Obtain your own Google Maps API key from here.

Functions

Functions which operate on locations are:

distance-between location1 location2 &key (unit :miles)

This calculates the straight line distance on the surface of the earth between LOCATION1 and LOCATION2 using the "Great Circle Distance Formula". The values of the keyword UNIT can be :miles (the default), :nautical-miles or :kilometers.

location-near-p location reference within

Return true if LOCATION is near REFERENCE (a location) to WITHIN decimal degrees in both latitude and longitude.

place-to-location place &key (key *default-key*)

Return the location corresponding to PLACE.

location-to-place location

Return the place corresponding to LOCATION.

Implementation Details

place-to-location is pretty straightforward. The Google Maps API converts the place to a location.

location-to-place, however, is a little trickier. There is no readily available web resource that will do this (like Google Maps). I did find The Zip Code Database Project which contains location coordinates for each zip code, and the data includes the names of the cities for each zip code. It's a fairly simple matter to find the nearest match for a set of coordinates.

So, imbedded in cl-geocode is the function location-to-zipcode:

cl-user(24): (location-to-zipcode (place-to-location "Oakland, CA"))
#<zipcode 94612 (Oakland, California): 37.809425,-122.27172>
cl-user(25): 

and

cl-user(31): (location-to-zipcode (place-to-location "1 Infinite Loop"))
#<zipcode 94087 (Sunnyvale, California): 37.35009,-122.03602>
cl-user(32): 

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-geocode

Dependencies
Source

cl-geocode.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-geocode.asd

Location

cl-geocode.asd

Systems

cl-geocode (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-geocode/package.lisp

Parent

cl-geocode (system)

Location

package.cl

Packages

cl-geocode

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-geocode/zip-util.lisp

Parent

cl-geocode (system)

Location

zip-util.cl

Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 cl-geocode/geocode.lisp

Dependencies
Parent

cl-geocode (system)

Location

geocode.cl

Exported Definitions
Internal Definitions

*place-to-location-re* (special variable)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-geocode

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *default-key*

A default Google Maps API key for calls to geocode. You can obtain a key by visiting http://www.google.com/apis/maps/signup.html.

Package

cl-geocode

Source

geocode.lisp (file)

Special Variable: *zipcodes*
Package

cl-geocode

Source

geocode.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: distance-between LOCATION1 LOCATION2 &key UNIT

Calculate the straight line distance on the surface of the earth between LOCATION1 and LOCATION2 using the "Great Circle Distance Formula". The values of the keyword UNIT can be :miles (the default), :nautical-miles or :kilometers.

Package

cl-geocode

Source

geocode.lisp (file)

Function: geocode &key Q KEY OUTPUT

Geocoding is the process of converting addresses (like "1600 Amphitheatre Parkway, Mountain View, CA") into geographic coodinates (like latitude 37.423021 and longitude -122.083739), which you can use to place markers or position the map based on street addresses in your database or addresses supplied by users. The Google Maps API includes a geocoder that can be accessed via HTTP request.

Package

cl-geocode

Source

geocode.lisp (file)

Function: location-latitude INSTANCE
Function: (setf location-latitude) VALUE INSTANCE
Package

cl-geocode

Source

package.lisp (file)

Function: location-longitude INSTANCE
Function: (setf location-longitude) VALUE INSTANCE
Package

cl-geocode

Source

package.lisp (file)

Function: location-near-p LOCATION REFERENCE WITHIN

Is LOCATION near REFERENCE location to WITHIN decimal degrees in both latitude and longitude?

Package

cl-geocode

Source

geocode.lisp (file)

Function: location-to-place LOCATION
Package

cl-geocode

Source

geocode.lisp (file)

Function: location-to-zipcode LOCATION
Package

cl-geocode

Source

geocode.lisp (file)

Function: make-location &key (LATITUDE LATITUDE) (LONGITUDE LONGITUDE)
Package

cl-geocode

Source

package.lisp (file)

Function: place-to-location PLACE &key KEY &aux RE
Package

cl-geocode

Source

geocode.lisp (file)

Function: zipcode-city INSTANCE
Function: (setf zipcode-city) VALUE INSTANCE
Package

cl-geocode

Source

package.lisp (file)

Function: zipcode-code INSTANCE
Function: (setf zipcode-code) VALUE INSTANCE
Package

cl-geocode

Source

package.lisp (file)

Function: zipcode-p OBJECT
Package

cl-geocode

Source

package.lisp (file)

Function: zipcode-state INSTANCE
Function: (setf zipcode-state) VALUE INSTANCE
Package

cl-geocode

Source

package.lisp (file)

Function: zipcode-state-abbrev INSTANCE
Function: (setf zipcode-state-abbrev) VALUE INSTANCE
Package

cl-geocode

Source

package.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Structures

Structure: location ()
Package

cl-geocode

Source

package.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods
  • make-load-form (method)
  • print-object (method)
Direct slots
Slot: latitude
Readers

location-latitude (function)

Writers

(setf location-latitude) (function)

Slot: longitude
Readers

location-longitude (function)

Writers

(setf location-longitude) (function)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *place-to-location-re*
Package

cl-geocode

Source

geocode.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: copy-location INSTANCE
Package

cl-geocode

Source

package.lisp (file)

Function: copy-zipcode INSTANCE
Package

cl-geocode

Source

package.lisp (file)

Function: location-p OBJECT
Package

cl-geocode

Source

package.lisp (file)

Function: make-zipcode &key (CODE CODE) (STATE-ABBREV STATE-ABBREV) (LOCATION LOCATION) (CITY CITY) (STATE STATE)
Package

cl-geocode

Source

package.lisp (file)

Function: read-zipcodes-csv CSV-FILE
Package

cl-geocode

Source

zip-util.lisp (file)

Function: vector-of VECTOR FUNCTION
Package

cl-geocode

Source

zip-util.lisp (file)

Function: zipcode-location INSTANCE
Function: (setf zipcode-location) VALUE INSTANCE
Package

cl-geocode

Source

package.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Structures

Structure: zipcode ()
Package

cl-geocode

Source

package.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots
Slot: code
Readers

zipcode-code (function)

Writers

(setf zipcode-code) (function)

Slot: state-abbrev
Readers

zipcode-state-abbrev (function)

Writers

(setf zipcode-state-abbrev) (function)

Slot: location
Readers

zipcode-location (function)

Writers

(setf zipcode-location) (function)

Slot: city
Readers

zipcode-city (function)

Writers

(setf zipcode-city) (function)

Slot: state
Readers

zipcode-state (function)

Writers

(setf zipcode-state) (function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-geocode.asd: The cl-geocode<dot>asd file
cl-geocode/geocode.lisp: The cl-geocode/geocode<dot>lisp file
cl-geocode/package.lisp: The cl-geocode/package<dot>lisp file
cl-geocode/zip-util.lisp: The cl-geocode/zip-util<dot>lisp file

F
File, Lisp, cl-geocode.asd: The cl-geocode<dot>asd file
File, Lisp, cl-geocode/geocode.lisp: The cl-geocode/geocode<dot>lisp file
File, Lisp, cl-geocode/package.lisp: The cl-geocode/package<dot>lisp file
File, Lisp, cl-geocode/zip-util.lisp: The cl-geocode/zip-util<dot>lisp file

L
Lisp File, cl-geocode.asd: The cl-geocode<dot>asd file
Lisp File, cl-geocode/geocode.lisp: The cl-geocode/geocode<dot>lisp file
Lisp File, cl-geocode/package.lisp: The cl-geocode/package<dot>lisp file
Lisp File, cl-geocode/zip-util.lisp: The cl-geocode/zip-util<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
C   D   F   G   L   M   P   R   V   Z  
Index Entry  Section

(
(setf location-latitude): Exported functions
(setf location-longitude): Exported functions
(setf zipcode-city): Exported functions
(setf zipcode-code): Exported functions
(setf zipcode-location): Internal functions
(setf zipcode-state): Exported functions
(setf zipcode-state-abbrev): Exported functions

C
copy-location: Internal functions
copy-zipcode: Internal functions

D
distance-between: Exported functions

F
Function, (setf location-latitude): Exported functions
Function, (setf location-longitude): Exported functions
Function, (setf zipcode-city): Exported functions
Function, (setf zipcode-code): Exported functions
Function, (setf zipcode-location): Internal functions
Function, (setf zipcode-state): Exported functions
Function, (setf zipcode-state-abbrev): Exported functions
Function, copy-location: Internal functions
Function, copy-zipcode: Internal functions
Function, distance-between: Exported functions
Function, geocode: Exported functions
Function, location-latitude: Exported functions
Function, location-longitude: Exported functions
Function, location-near-p: Exported functions
Function, location-p: Internal functions
Function, location-to-place: Exported functions
Function, location-to-zipcode: Exported functions
Function, make-location: Exported functions
Function, make-zipcode: Internal functions
Function, place-to-location: Exported functions
Function, read-zipcodes-csv: Internal functions
Function, vector-of: Internal functions
Function, zipcode-city: Exported functions
Function, zipcode-code: Exported functions
Function, zipcode-location: Internal functions
Function, zipcode-p: Exported functions
Function, zipcode-state: Exported functions
Function, zipcode-state-abbrev: Exported functions

G
geocode: Exported functions

L
location-latitude: Exported functions
location-longitude: Exported functions
location-near-p: Exported functions
location-p: Internal functions
location-to-place: Exported functions
location-to-zipcode: Exported functions

M
make-location: Exported functions
make-zipcode: Internal functions

P
place-to-location: Exported functions

R
read-zipcodes-csv: Internal functions

V
vector-of: Internal functions

Z
zipcode-city: Exported functions
zipcode-code: Exported functions
zipcode-location: Internal functions
zipcode-p: Exported functions
zipcode-state: Exported functions
zipcode-state-abbrev: Exported functions

Jump to:   (  
C   D   F   G   L   M   P   R   V   Z  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
C   L   S  
Index Entry  Section

*
*default-key*: Exported special variables
*place-to-location-re*: Internal special variables
*zipcodes*: Exported special variables

C
city: Internal structures
code: Internal structures

L
latitude: Exported structures
location: Internal structures
longitude: Exported structures

S
Slot, city: Internal structures
Slot, code: Internal structures
Slot, latitude: Exported structures
Slot, location: Internal structures
Slot, longitude: Exported structures
Slot, state: Internal structures
Slot, state-abbrev: Internal structures
Special Variable, *default-key*: Exported special variables
Special Variable, *place-to-location-re*: Internal special variables
Special Variable, *zipcodes*: Exported special variables
state: Internal structures
state-abbrev: Internal structures

Jump to:   *  
C   L   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   L   P   S   Z  
Index Entry  Section

C
cl-geocode: The cl-geocode system
cl-geocode: The cl-geocode package

L
location: Exported structures

P
Package, cl-geocode: The cl-geocode package

S
Structure, location: Exported structures
Structure, zipcode: Internal structures
System, cl-geocode: The cl-geocode system

Z
zipcode: Internal structures

Jump to:   C   L   P   S   Z