Placeable Locator API v1

This is a read-only REST API that enables remote applications to consume local search data and offer geospatial search capabilities.

Authorization

The API is secured using a pre-shared key. Each request to the API must have this as a parameter, or the service will respond with an HTTP status code of 400.

Method: GET

Parameter: key

Required: TRUE

Example:

 /v1/search?q=fargo&key=c12226cc85f0662db6aa21d1b5c7b664adb41497

NOTE: This API key has been omitted from the other examples in the documentation for brevity and clarity.

To obtain your auth key, contact your account manager, or support@placeable.com

Standard Search

Method: GET

URL: /v1/search

Examples:

/v1/search?q=colorado+springs

or

http://your.domain.com/v1/search?q=colorado+springs

NOTE: The example assume you have the API activated, and have data loaded for you site in Colorado Springs.

Parameters

q (as in q=80202)

Required: TRUE

Description: The default search parameter to search for a location. This must be URL encoded.

Example:

/v1/search?q=Denver%20CO

You can also search by lat & long. Just pass the parameters as shown below:

/v1/search?q=latitude:39.770224029999994;longitude:-105.02012416 

The colons : and the semicolon ; are required.

sortOrder

Required: FALSE

Options: “Distance, NameAZ, NameZA”

Description: • Distance is the distance from the point where “q” is geocoded. • NameAZ is the results ordered by name in descending order • NameZA is the results ordered by name in ascending order

Example:

/v1/search?q=Denver%20CO&sortOrder=NameAZ

filters

Required: FALSE

These are specific to your data. If your data has "atmLanguages" with the options of "english, french and spanish" and you want to filter down to only "english" locations the URL would look like:

/v1/search?q=Denver%20CO&filters=atmLanguages-_-english  

and if you'd like to filter in english and spanish the URL would look like:

/v1/search?q=Denver%20CO&filters=atmLanguages-_-english-_-spanish   

The _-_ is the delimiter between filter/value pairs.

refinements

Required: FALSE

Options: true

Description: • This option will expose the pre-configured filter options and filter groups for the result set.

Example:

/v1/search?q=Denver%20CO&refinements=true

	refinements: [
	{
		filterName: "filter",
		filterValues: [
			{
				name: "filter-_-ABM",
				count: 560
			},
			{
				name: "filter-_-Branch",
				count: 217
			},
			{
				name: "filter-_-Pavilion",
				count: 46
			}
				]
	},
	{
		filterName: "locationTypeFilter",
		filterValues: [
			{
				name: "locationTypeFilter-_-BranchABM",
				count: 568
			},
			{
				name: "locationTypeFilter-_-ABM",
				count: 560
			},
			{
				name: "locationTypeFilter-_-PavilionABM",
				count: 397
			},
			{
				name: "locationTypeFilter-_-Branch",
				count: 217
			},
			{
				name: "locationTypeFilter-_-Pavilion",
				count: 46
			}
				]
	},

In the example above, there are 560 locations matching the filter "filter--ABM", 217 locations matching the filter "filter--Branch", etc.

page_size

Required: FALSE

Options: A numeric value between 1 and 50

Description: • page_size sets the number of results returned per page. If page_size=25 and there are 100 results, there will be 4 pages, 25 results each. • If page_size is set to > 50, then 50 results will be returned per page. • If page_size is not set, the page_size as configured in the locator will be used.

Example:

/v1/search?q=Denver%20CO&page_size=10

page

Required: FALSE

Options: Return a different page of the result sets.

Example: Return the second page

 /v1/search?q=Denver%20CO&sortOrder=NameAZ&page=2

mask

Required: FALSE

Options: Must be set to a pre-configured mask name

Description: • By default, the API will return all of the available data fields. If it is neccesary to return only a subset of the data, say for performance considerations, a "mask" can be configured.
• Multiple masks can be set up per API • Data masks need to be configured for each API. See your Account Manager for details.

Example (assuming there is a configured mask named "short_set")

/v1/search?q=Denver%20CO&mask=short_set

callback

Required: FALSE

Options: Return the json wrapped in the specified callback. This paramater allows the response to be JSONP compatible. The ContentType for all calls with a callback is 'aplication/javascript'. Also, the response code for JSONP calls is always 200.

Example: Wraps the json in "test" callback

 /v1/search?q=Denver%20CO&sortOrder=NameAZ&callback=test

Advanced Search

Method: GET

URL: /v1/search

Examples:

/v1/search?t=80033&f=postal

or

http://your.domain.com/v1/search?t=80033&f=postal

Parameters

t (as in t=80033)

Required: TRUE

Description: The term that you would like to search for. This must be URL encoded.

Example:

/v1/search?t=80033

f (as in f=postal)

Required: TRUE

Description: The field that the term should be queried against. The field name must match the database and only fields that are made searchable by an administrator can be queried.

Example:

/v1/search?t=80033&f=postal

You can also include multiple fields in your search. Just pass the parameters as shown below:

v1/search?t=80033&f=postal,streetAddress

Response Details

The response consists of location data, and results. The location section contains information about where the search was carried out, and the results section contains the list of results that were found plus some metadata about the result set.

Location

    "searched": {
        "adminDistrict": "CO", 
        "country": "United States", 
        "entityType": "Address", 
        "formattedAddress": "2601 Blake St, Denver, CO 80205", 
       	"locality": "Denver", 
        "latitude": 39.7603645324707, 
        "longitude": -104.987144470215, 
        "street": "2601 Blake St"
    }
Key Value
adminDistrict State
country Country
entityType Type of location returned e.g address, city, state, country
formattedAddress Representaton of the address found
locality City
latitude Latitude
longtitude Longtitude
street Street

It is possible that some of the above value may be blank given the search supplied. For example you enter Colorado as the search, the search and locality will be blank.

NOTE: The Location data gets populated into the Pages Database via the Workbench Tool. The workflow defined for the pages API exports only active locations. This means that when you use the Pages API to retrieve locations, the inactive locations will not be displayed within the results returned.

Paging

Under the results section of the API response there information about paging. The resultCount is the total number of records returned by the search, and the pageCount is the total number of pages. The user can request a different page from the result set by querying with the page parameter (explained above)

No Results found

Below is an example of a search which returned zero results

	{
	    "location": {
	        "candidates": [], 
	        "searched": {
	            "adminDistrict": "AK", 
	            "country": "United States", 
	            "entityType": "PopulatedPlace", 
	            "formattedAddress": "Nome, AK", 
	            "latitude": 64.49947357177734, 
	            "locality": "Nome", 
	            "longitude": -165.40579223632812, 
	            "street": ""
	        }
	    }, 
	    "results": {
	        "resultCount": 0, 
	        "results": []
	    }
	}

Errors

Below are the different types of errors that can occur if the right information is not provided to the api.

Status Code Description
400 No auth key provided, or bad request, or json is not allowed for the site
401 Unauthorized api key.
404 Couldn't find search origin given the q parameter, or unknown location

No Auth Key Provided (400)

	{
	    "error": "Key is required to search the API."
	}

Json not allowed (400)

	{
	    "error": ""Json is not allowed for 'site'.""
	}

Invalid Key Provided(401)

	{
	    "error": "This key ('invalid key name') has not been authorized"
	}

Unknown Location(404)

	{
	    "error": "Unknown location"
	}		

Full Response

Below is a full response, for each result any flexible fields which have been loaded during the dataload will be passed directly through.

	    {
		    "location": {
		        "candidates": [], 
		        "searched": {
		            "adminDistrict": "CO", 
		            "country": "United States", 
		            "entityType": "Address", 
		            "formattedAddress": "2601 Blake St, Denver, CO 80205", 
		            "latitude": 39.7603645324707, 
		            "locality": "Denver", 
		            "longitude": -104.987144470215, 
		            "street": "2601 Blake St"
		        }
		    }, 
		    "results": {
		        "distanceUnit": "miles", 
		        "pageCount": 1, 
		        "resultCount": 1, 
		        "sortOrder": "Distance",
		        "results": [
		            {
		                "id": "81341",
		                "city": "DENVER", 
		                "detail.languages": [
		                    "English", 
		                    " Spanish"
		                ], 
		                "detail.services": [
		                    "Bulk Mail Acceptance", 
		                    "Bulk Mail Account Balance", 
		                    "Bulk Mail New Permit", 
		                    "Burial Flags", 
		                    "Business Reply Mail Account Balance", 
		                    "Business Reply Mail New Permit", 
		                    "Duck Stamps"
		                ], 
		                "detailsUrl": "co/denver/81341", 
		                "distance": 1.5261252679006334, 
		                "email": "", 
		                "fax": "303-951-3484", 	           
		                "custom.languages": {
		                    "ENG": "English", 
		                    "SPA": "Spanish"
		                }, 
		                
		                "languages": "English, Spanish", 
		                "lastModified": "Wed, 28 Aug 2013 05:36:43 245 -0600", 
		                "latitude": "39.759108", 
		                "location": "39.759108,-105.015829", 
		                "longitude": "-105.015829", 
		                "name": "Mile High", 
		                "phone": " 303-571-0722", 
		                "result.languages": [
		                    "English", 
		                    " Spanish"
		                ], 
		                "result.services": [
		                    "Bulk Mail Acceptance", 
		                    "Bulk Mail Account Balance", 
		                    "Bulk Mail New Permit", 
		                    "Burial Flags", 
		                    "Business Reply Mail Account Balance", 
		                    "Business Reply Mail New Permit", 
		                    "Duck Stamps"
		                ], 
		                "services":  "Bulk Mail Acceptance,Bulk Mail Account Balance,Bulk Mail New Permit,Burial Flags,Business Reply Mail Account Balance,Business Reply Mail New Permit,Duck Stamps",
		                "state": "CO", 
		                "streetAddress": "450 W 14TH AVE", 
		                "streetAddress2": "", 
		                "type": "Branch", 
		                "webUrl": "http://geocities.com/mileHighLocation", 
		                "zip": "80204-9998"
		            }
		        ]
		        
		    }
		}

Comments

0 comments

Please sign in to leave a comment.