Skip to content

nmdguerreiro/lua-resty-opencage-geocoder

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
t
 
 
 
 
 
 
 
 
 
 
 
 
 
 

lua-resty-opencage-geocoder

This Lua module provides a simple client for the OpenCage forward/reverse geocoding API, to be used with OpenResty.

Installation

To install this module, run the following command using the OpenResty package manager:

opm get nmdguerreiro/lua-resty-opencage-geocoder

Sample usage

See the sample nginx configuration file. It contains an example of how to make calls to the OpenCage API. Note: You'll need to replace your API key in the configuration file before starting nginx. Once you've done that, you can run:

./nginx_sample.sh

After starting nginx you should be able to get some results:

$ curl localhost:8080


Result: {"timestamp":{"created_http":"Sat, 24 Feb 2018 19:21:44 GMT","created_unix":1519500104},"documentation":"https:\/\/geocoder.opencagedata.com\/api","thanks":"For using an OpenCage Data API","stay_informed":{"blog":"https:\/\/blog.opencagedata.com","twitter":"https:\/\/twitter.com\/opencagedata"},"results":[{"geometry":{"lng":13.3777025,"lat":52.5162767},"components":{"_type":"attraction","ISO_3166-1_alpha-2":"DE","suburb":"Mitte","state":"Berlin","road":"Pariser Platz","political_union":"European Union","house_number":"1","city":"Berlin","city_district":"Mitte","country":"Germany","postcode":"10117","country_code":"de","attraction":"Brandenburg Gate"},"confidence":9,"bounds":{"southwest":{"lng":13.37758,"lat":52.5161167},"northeast":{"lng":13.377825,"lat":52.5164327}},"formatted":"Brandenburg Gate, Pariser Platz 1, 10117 Berlin, Germany"},{"geometry":{"lng":-91.554716,"lat":34.515457},"components":{"_type":"road","state":"Arkansas","town":"Stuttgart","state_code":"AR","county":"Arkansas County","postcode":"72160","country":"United States of America","road":"Brandenburg Gate","country_code":"us","ISO_3166-1_alpha-2":"US"},"confidence":9,"bounds":{"southwest":{"lng":-91.5575726,"lat":34.515457},"northeast":{"lng":-91.554716,"lat":34.5155269}},"formatted":"Brandenburg Gate, Stuttgart, AR 72160, United States of America"}],"licenses":[{"url":"http:\/\/creativecommons.org\/licenses\/by-sa\/3.0\/","name":"CC-BY-SA"},{"url":"http:\/\/opendatacommons.org\/licenses\/odbl\/summary\/","name":"ODbL"}],"total_results":2,"rate":{"limit":2500,"reset":1519516800,"remaining":2481},"status":{"message":"OK","code":200}}

Forward geocoding

To perform a forward geocoding request, all you need to do is instantiate the client and make the geocode call as is shown below:

local geocoder = require "opencage.geocoder"

local gc = geocoder.new({
  key = "REPLACE WITH YOUR KEY"
})

local res, status, err = gc:geocode("Brandenburg Gate")

gc.close()

Remember to close the client, so any underlying connections can be closed when you're done.

Reverse geocoding

Similarly, to issue a reverse geocoding request, all you need to do is instantiate the client and make the reverse_geocode call as is shown below:

local geocoder = require "opencage.geocoder"

local lat, long = 52.5162767, 13.3777025

local gc = geocoder.new({
  key = "REPLACE WITH YOUR KEY"
})

local res, status, err = gc:reverse_geocode(lat, long)

gc.close()

Again, remember to close the client, so any underlying connections can be closed when you're done.

Error handling

Calls to geocode and reverse_geocode return three values:

  • The table that represents the JSON returned by the OpenCage API.
  • A status code
  • An error message, if applicable

For convenience, the status codes are available on the client object itself and are defined as per below (and in-line with the API guide):

gc.status_ok = 200
gc.status_invalid_request = 400
gc.status_quota_exceeded = 402
gc.status_invalid_key = 403
gc.status_timeout = 408
gc.status_request_too_long = 410
gc.status_rate_exceeded = 429
gc.status_internal_server_error = 503

So, you can handle errors like so:

local res, status, err = gc:geocode("Brandenburg Gate", params)

if (status = gc.status_invalid_key) then
    ngx.log(ngx.ERR, "It seems we forgot to set our API key correctly :-)")
end

Parameters

You can supply any additional parameters to help improve your results, as is described in the API guide. For example:

local geocoder = require "opencage.geocoder"

local gc = geocoder.new({
  key = "REPLACE WITH YOUR KEY"
})

params = { abbrv = 1 }
local res, status, err = gc:geocode("Brandenburg Gate", params)

gc.close()

Connection settings

This module depends on lua-resty-http, which enables you to configure connection and request timeouts. To set the timeout, use the timeout parameter:

local gc = geocoder.new({
  key = "REPLACE WITH YOUR KEY",
  timeout = 5000, -- maximum timeout in milliseconds
})

Licence

MIT

About

OpenResty Lua module for use with the OpenCage Forward/Reverse Geocoding API

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published