rodeo

A Clojure library designed to be a thin wrapper over the Geocodio API.

Installation

Leiningen

[rodeo "2.0.1"]

Maven

<dependency>
  <groupId>rodeo</groupId>
  <artifactId>rodeo</artifactId>
  <version>2.0.1</version>
</dependency>

Gradle

compile "rodeo:rodeo:2.0.1"

Usage

NOTE: This version has breaking changes from 1.0.0!

You must acquire an API key from the Geocodio site

Then, either set the GEOCODIO_API_KEY envrionment variable with the API key or pass it into the Rodeo functions as described below using the :api-key key.

Acceptable address formats are detailed here

Optionally, extra fields such as congressional district and timezone may be specified using the :fields key as outlined below. This feature is available on every endpoint except the components endpoint.

All functions return a Clojure map. The map will contain an :error key with a description if there was an error. Otherwise, it will return a map containing the response. My humble suggestion is to use core.match to perform error handling for responses with an :error key and regular handing for success responses. However, since you'll get a map back regardless, it is completely up to you to decide on an error handling strategy.

Geocoding

Returns a Clojure map with a parsed address and geolocation information

(ns my.ns
  (:require [rodeo.core :refer :all]))

;;; batch addresses

;; with environment variable

(batch ["42370 Bob Hope Dr, Rancho Mirage CA" "54 West Colorado Boulevard, Pasadena, CA 91105"])

;; without environment variable

(batch ["42370 Bob Hope Dr, Rancho Mirage CA" "54 West Colorado Boulevard, Pasadena, CA 91105"] 
  :api-key "api-key-here")

;; with extra fields specified
(batch ["42370 Bob Hope Dr, Rancho Mirage CA" "54 West Colorado Boulevard, Pasadena, CA 91105"] 
  :api-key "api-key-here" :fields ["cd" "stateleg"])


;;; single addresses

(single "42370 Bob Hope Dr, Rancho Mirage CA")

(single "42370 Bob Hope Dr, Rancho Mirage CA" :api-key "api-key-here")

(single "42370 Bob Hope Dr, Rancho Mirage CA" :api-key "api-key-here" :fields ["cd"])

Reverse Geocoding

Given a seq of lat long pairs, returns a Clojure map with address information

(single-reverse "42.584149,-71.005885")
(single-reverse "42.584149,-71.005885" :api-key "api-key-here")
(single-reverse "42.584149,-71.005885" :api-key "api-key-here" :fields ["stateleg"])

(batch-reverse ["42.584149,-71.005885" "34.1455496,-118.151631"])
(batch-reverse ["42.584149,-71.005885" "34.1455496,-118.151631"] :fields ["stateleg"])
(batch-reverse ["42.584149,-71.005885" "34.1455496,-118.151631"] :api-key "api-key-here")

Parsing Components

Returns a Clojure map containing just the parsed address (street, city, etc)

(components "42370 Bob Hope Dr, Rancho Mirage CA")
(components "42370 Bob Hope Dr, Rancho Mirage CA" :api-key "api-key-here")

License

Distributed under the Eclipse Public License (same as Clojure) either version 1.0 or (at your option) any later version.

jboverfelt / rodeo