There are two ways in which developers can access StopFinder functionality. The first way is the simplest: You can embed our maps by linking to a StopFinder URL in an IFRAME, much like you can do with Google Maps. The second way is by writing programs that access the StopFinder web service.
You can embed a StopFinder map into your own webpage by copying the iframe specification in the textarea below. You can adjust the width and height of the displayed map by changing the width and height properties on the iframe. You must specify all URL parameters as shown in the example; if you leave one out, you'll see an empty skeleton of the normal StopFinder map interface. You can, however, specify blank values for the staying and arrival_time parameters (e.g. write "staying=") to specify that you want StopFinder to generate defaults like it does on the main site.
The StopFinder API allows you to programmatically access the same functionality that is available to the users of our website. We provide a few more filtering options in the API that are currently absent from the public interface, but it still does more or less the same thing: Allows you to find parking lots and transit stops within some radius of a point of interest.
The API is exposed through a single call that can be invoked via HTTP post to the url http://stopfinder.com/sfapi/. The parameters to this call are the following:
| Name | Acceptable values | Required? | Description |
|---|---|---|---|
| latitude | Float | Yes. | The latitude of your point of interest. |
| longitude | Float | Yes. | The longitude of your point of interest. |
| include_lots | "True" or "False" | No. | Do you want parking lots returned in the result of this query? |
| include_subways | "True" or "False" | No. | Do you want subways returned in the result of this query? |
| include_busstops | "True" or "False" | No. | Do you want bus stops returned in the result of this query? |
| arrival_day | "MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN", "" | No. | The day you expect to arrive. If this is blank, no time-based filtering will be performed on the parking lot results. |
| arrival_time | Almost any human-intelligible time ("2pm", "10:20", etc.) or "". | No. | The time you expect to arrive. If this is blank, no time-based filtering will be performed on the parking lot results. |
| staying | Float | No. | The time, in hours, you expect to park for. If this is blank, no filtering will be performed on lots with time limits or closing hours. |
From this table, you can see that you must specify both an arrival day and an arrival time to trigger any time-based filtering of lots. Also, you must specify a staying time if you want filtering based on time limits. Finally, you must specify all of these values if you want the cheapest lot identified. These time and duration parameters have no effect on transit results.
You may have noticed that our API does not accept a querystring as a parameter. You are required to know the latitude and the longitude of your point of interest before issuing your query. The process of translating the description of an address into a latitude and longitude is known as geocoding.
Right now, geocoding is a limited resource for StopFinder, and so we can't yet afford to have the API consuming our geocoding services as well. Luckily, it's really easy -- and free! -- to access several public geocoding services out there on the internet. Probably the most popular is the Google Maps geocoder, which you can read about here.
If you're using Python, we strongly recommend geopy if you don't want to write your own wrapper for the geocoding web service of your choice.
Our API responds to your requests in plain old XML. We're talking really plain. We don't even have a schema written up for it yet.
We could describe to you in great, gory detail what each of the elements means, but instead we will refer you to this sample output. It should be fairly self-explanatory. If you'd like more detail about the datatypes being returned, you can check out the Python API client, which is thoroughly documented.
If there are errors in your inputs, you'll get a (non-XML) response back that outlines exactly what we didn't like about what you asked us to do. The status code on this response is still 200, though, so watch out.
This form sends a POST to the StopFinder API so that you can get an idea of how it works. You're going to need a geocoder to figure out your latitudes and longitudes, though. Like this one, for example.
If you don't feel like writing your own wrapper for our service, you can make use of our Python API client, available here. This module provides Python classes that represent StopFinder datatypes, as well as a class called StopFinderAPIClient that knows how to query the service and marshal the XML result into instances of those model classes. The query functionality is available through a single method on the client called find_stops.
The client tends to explode when you send bad parameters to the service. So, you might want to guard calls to find_stops with a try/except block.
Please use the API gently. We don't want to have to throttle it because someone is hammering our service hard enough to negatively effect the experience of our users.
But we know y'all are nice folks, so we don't think we're going to have to do this.
We're excited to see what you come up with! If you use our API for something in particular, please let us know and we'll publicize it on our site.
Further questions can be sent to Debo at debo@stopfinder.com.
Enjoy!
