Skip to content

OpenCage CFC provides a CFML wrapper for the OpenCage Geocoder API

License

Notifications You must be signed in to change notification settings

GaryStanton/OpenCageCFC

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

OpenCage CFC

OpenCageCFC provides a wrapper for the OpenCage Geocoder API.
The opencage API is a commercial product with a generous free tier.
Obtain an API key from https://opencagedata.com/users/sign_up.

Installation

box install opencage

Usage

instantiate the component and pass your API key to the constructor. You may do this standalone:

var opencage  = new opencage.models.opencage(
    aipKey = 'YOURAPIKEY'
);

or with ColdBox:

var opencage  = getInstance("opencage@opencage");

alternatively inject it directly into your handler

property name="opencage" inject="opencage@opencage";

When using with ColdBox, you'll want to insert your API key into your module settings:

opencage = {
    apiKey = getSystemSetting( "OPENCAGE_KEY", "" )
}

Query

The opencage CFC wrapper contains a single method, query, which will return the response from the opencage API.

data = opencage.query(
    	q = 'British Library, 96 Euston Road, London NW1 2DB'
    ,   responseFormat = 'json'
);

The query method accepts the following parameters:

parameter type description
q string The query string to be geocoded - a latitude, longitude or a placename/address.
When reverse geocoding the query should be in latitude, longitude order in decimal format. For example: 51.952659, 7.632473. There is no reason to send more than six or seven digits past the decimal as that then gets down to the precision of a centimeter. If impossible coordinates are supplied you will receive a 400 invalid coordinates as the response code in the status section of the response.
responseFormat string The response format (json ¦ geojson ¦ xml ¦ map). Defaults to json.
abbrv boolean If true, attempt to abbreviate and shorten the formatted string we return.
add_request boolean If true, the various request parameters are added to the response for ease of debugging.
bounds string Used only for forward geocoding. This value will restrict the possible results to a defined bounding box.
The value of the bounds parameter should be specified as two coordinate points forming the south-west and north-east corners of a bounding box. For example: bounds=-0.563160,51.280430,0.278970,51.683979 (min lon, min lat, max lon, max lat).
Values that are not valid coordinates are ignored.
countrycode string Used only for forward geocoding. Restricts results to the specified country/territory or countries.
The country code is a two letter code as defined by the ISO 3166-1 Alpha 2 standard. E.g. gb for the United Kingdom, fr for France, us for United States.
Non-two letter country codes are ignored.
You can specify multiple country codes by supplying a comma separated list. For example countrycode=ca,us would limit results to either the United States or Canada.
Please note, many territories have their own ISO 3116-1 codes, despite being part of another country. An example is Puerto Rico which has ISO code PR, despite being part of the United States, US. In the components portion of results we return both.
Many parts of the world have complex or even disputed political structures and/or share postal systems with another country, and thus may be treated as a single or multiple country by some of the geocoders we rely upon. It may make sense to specify multiple country codes.
As an example, when searching for locations on the island of Aruba - technically a constituent country of the Kingdom of the Netherlands - we will do better if you specify countrycode=aw,nl rather than just countrycode=aw.
jsonp boolean Wraps the returned JSON with a function name.
language string An IETF format language code (such as es for Spanish or pt-BR for Brazilian Portuguese), or native in which case we will attempt to return the response in the local language(s).
Please note, setting the language parameter does NOT mean results will only be returned in the specified language. Instead it means we will attempt to favour results in that language.
limit numeric The maximum number of results we should return. Default is 10. Maximum allowable value is 100.
min_confidence numeric An integer from 1-10. Only results with at least this confidence will be returned.
no_annotations boolean When true results will not contain annotations.
no_dedupe boolean When true results will not be deduplicated.
no_record boolean When true the query contents are not logged.
pretty boolean When true results are 'pretty' printed for easier reading. Useful for debugging.
proximity string Used only for forward geocoding. Provides the geocoder with a hint to bias results in favour of those closer to the specified location. Please note though, this is just one of many factors in the internal scoring we use for ranking results. The value is a point with latitude, longitude coordinates in decimal format. For example: 51.952659, 7.632473
Values that are not valid coordinates are ignored.
roadinfo string When true the behaviour of the geocoder is changed to attempt to match the nearest road (as opposed to address). If possible we also fill additional information in the roadinfo annotation.