Find Biodiesel API 1.0

The Find Biodiesel API allows software developers and content providers to use Find Biodiesel's search features and comprehensive database of worldwide biodiesel stations in their own applications. Use of the Find Biodiesel API is free, but you must obtain an API key first.

What Can I Do with the Find Biodiesel API?

Obtaining an API Key

To obtain an API Key, send an email to nate@nateclark.com with your Name, Company Name (if any), Phone Number, and a brief description of how you will use the API data.

Usage Limitations

Usage is limited to 5,000 requests per day. This is mainly to keep server costs under control. If you expect to require more than 5,000 requests per day, please contact me about raising your API usage limit.


API Documentation


locations

The Find Biodiesel API currently only supports one operation, locations. The locations operation expects a location query (i.e. zip code, address, or city/state) and optional parameters, and returns a list of biodiesel stations within the specified radius of the location. You can envoke the locations operation with either a GET or POST request.

Parameters and Required Information

api_key (required)

The API key is unique to you, and must be provided with every request. This authorizes you to use the Find Biodiesel API. The API key is a string of 40 random characters.

q (required)

A url-encoded query for a specific location in any format acceptable by the Google Maps API. Typical queries are by postal code [q=94114]or city and state [q=San+Francisco%2C+CA]. You can also query a specific street address or intersection.

radius

Radius in miles or kilometers to search from the query location. This value must be a whole number. Default is 30. Maximum is 250

measure

Search in miles or kilometers. Default is miles. Possible values are miles or mi, kilometers or km.

limit

Maximum number of results to return. This value must be a whole number. Default is 10. Maximum is 50

fuel

The type of fuel stations to search for. Currently, the only possible value is biodiesel, which is also the default. This parameter will be used in the future to support other fueling station types.

Example Request Using GET method

  GET /api/locations?api_key=AAAAAAAA&q=94114&radius=25 HTTP/1.1
  Host: findbiodiesel.org

Example Request Using POST method

  POST /api/locations HTTP/1.1
  Host: findbiodiesel.org
  Content-Type: application/x-www-form-urlencoded
  Content-Length: length

  api_key=AAAAAAAA&q=94114&radius=25

Sample Successful Response

With comments added for documentation

 <!-- A successful request will generate an XML document with the requested data -->
  <?xml version="1.0" encoding="UTF-8"?>
  <Document>
  
   <!-- Confirmation of the request parameters are included with every successful response  -->
    <Request>
      <Query>San Francisco, CA</Query>
      <Limit>10</Limit>
      <Radius>30</Radius>
      <Measure>miles</Measure>
      <Fuel>biodiesel</Fuel>
      <Path>http://localhost:3000/api/locations</Path>
      <ApiUser>Test User</ApiUser>
    </Request>
    
    <Response>
    
     <!-- Respose codes and messages are similar to HTTP response codes  -->
      <Status>
        <Code>200</Code>
        <Message>Success</Message>
      </Status>
      
      <!-- The content of the response is summarized in this element  -->
      <Summary>Biodiesel stations within 30 miles of San Francisco, CA, US</Summary>
      
      <!-- The Place node represents the search center -->
      <Place>
      
        <!-- Address Details are represented using eXtensible Address Language -->
        <!-- see http://www.oasis-open.org/committees/ciq/ciq.html#6           -->
        <xAL version="2.0">
          <AddressDetails>
            <Country>
              <CountryNameCode>US</CountryNameCode>
              <AdministrativeArea>
                <AdministrativeAreaName>CA</AdministrativeAreaName>
                <SubAdministrativeArea>
                  <SubAdministrativeAreaName></SubAdministrativeAreaName>
                  <Locality>
                    <LocalityName>San Francisco</LocalityName>
                  </Locality>
                </SubAdministrativeArea>
              </AdministrativeArea>
            </Country>
          </AddressDetails>
        </xAL>
        
        <!-- Longitude and Latitude in decimal format -->
        <Point>
          <coordinates>-122.419204,37.775196</coordinates>
        </Point>
      </Place>
      
      <!-- The following text/HTML should be included in the same window, page, or view as the results -->
      <!-- returned by using the Find Biodiesel API                                                    -->
      <LinkBack>
        <![CDATA[Biodiesel stations search provided by <a href="http://localhost:3000/">Find Biodiesel</a>]]>
      </LinkBack>
      
      <!-- Begin listing Biodiesel Stations that match the search criteria -->
      <BiodieselStations>
        <Location>
          <Name>Olympian Oil Co.</Name>
          <Link isPermaLink="true">http://localhost:3000/locations/1503-Olympian-Oil-Co-San-Francisco-CA-US</Link>
          
          <!-- Fuel varieties carried at the location -->
          <Fuels>
            <BiodieselFuel>B20</BiodieselFuel>
          </Fuels>
          
          <Phone>(650) 873-8200</Phone>
          <Website>http://oly.com</Website>
          <Address>2690 3rd St, San Francisco, CA 94107</Address>
          
          <!-- Address Details are represented using eXtensible Address Language -->
          <!-- see http://www.oasis-open.org/committees/ciq/ciq.html#6           -->
          <xAL version="2.0">
            <AddressDetails>
              <Country>
                <CountryNameCode>US</CountryNameCode>
                <AdministrativeArea>
                  <AdministrativeAreaName>CA</AdministrativeAreaName>
                  <SubAdministrativeArea>
                    <SubAdministrativeAreaName></SubAdministrativeAreaName>
                    <Locality>
                      <LocalityName>San Francisco</LocalityName>
                      <Thoroughfare>
                        <ThoroughfareName>2690 3rd St</ThoroughfareName>
                      </Thoroughfare>
                      <PostalCode>
                        <PostalCodeNumber>94107</PostalCodeNumber>
                      </PostalCode>
                    </Locality>
                  </SubAdministrativeArea>
                </AdministrativeArea>
              </Country>
            </AddressDetails>
          </xAL>
        <Point>
          <coordinates>-122.388118,37.7555</coordinates>
        </Point>
          <AddedAt>Thu, 27 Sep 2007 20:24:02 GMT</AddedAt>
          <UpdatedAt>Thu, 27 Sep 2007 20:24:02 GMT</UpdatedAt>
        </Location>
         ... 
      </BiodieselStations>
    </Response>
  </Document>