Wednesday, August 14, 2013

Places API released

For the technically inclined sQuidders out there, we have just released a new Places API which allows you to retrieve all marinas, anchorages and other sQuidd.io places based on lat/lon coordinates from our database of over 10,000 boating destinations of interest worldwide. The API may be useful if you are creating geo-based applications such as marine charts and cruising guides. The results you get by using this particular API  call are the same you would obtain by searching for places through web UI, only in machine readable format.

The use of the API requires a sQuidd.io Business Account. If you have not yet signed up for one you can do so  at http://squidd.io/accounts/new. Business Accounts are free. Our APIs are REST-ful, and all responses are in JSON format. The basic request for a list of sQuidd.io Places looks like this:

http://squidd.io/places/?api_key=2CJ4ZIFWLPkuVitGs&latitude=37.589&longitude=-122.317&frame_size=1000

  • api_key: the API key associated with your business account. To obtain your key, go to your Account/Contact Info view and look for the value at the bottom of the form. 

  • latitude/longitude: the coordinates for the center of the search, in decimal format (south and east are negative numbers). 
  • frame_size: the half size of an approximate square centered on your lat/lon position, in meters. For instance, if you ar searching for all marinas and anchorages in the San Francisco Bay Area (latitude = 37.589, longitude=-122.317) with a frame_size of 1000, the results will include all places located in an area extending 1 Km north, 1 Km south, 1Km east and 1km West of  the specified coordinates. The maximum allowed value is 10,000.
And here is an example of the JSON response that this request would generate:

[
  {
    "address": "385 Oyster Point Blvd # 8A",
    "address2": null,
    "ais_unique_visitors": null,
    "city": "S San Francisco",
    "country_code": "US",
    "elevation": 6.615729808807373,
    "id": 1496,
    "latitude": 37.66389846801758,
    "longitude": -122.38500213623047,
    "name": "Oyster Cove Marina",
    "place_type": "Marina",
    "postal_code": "94080",
    "squiddio_url": "http://192.168.1.155:3000/places/1496",
    "state_code": "CA",
    "timezone": "America/Los_Angeles"
  },
  {
    "address": "400 Sierra Point Parkway",
    "address2": null,
    "ais_unique_visitors": null,
    "city": "Brisbane",
    "country_code": "US",
    "elevation": 5.1478800773620605,
    "id": 1493,
    "latitude": 37.673301696777344,
    "longitude": -122.37999725341797,
    "name": "City of Brisbane: Brisbane Marina",
    "place_type": "Marina",
    "postal_code": "94005",
    "squiddio_url": "http://192.168.1.155:3000/places/1493",
    "state_code": "CA",
    "timezone": "America/Los_Angeles"
  }
]