Developer API

Protocols

The VeganGuide API is implemented in XML-RPC using PHP XML-RPC

The API URI is https://veganguide.org/api

API Keys

Each API request requires an api key. You can get one in your account settings

Updates

  • 2009-02-07 1.0: Initial API Version

Feedback

If you have any feature suggestions, bug reports or other needs to get in touch with me concerning the API, just do it: api@veganguide.org.

Parameters

At first a word about parameters. The API always expects one XML/RPC <param />. the <value /> of this param is a <struct />, which of each <member /> is a parameter for the called method.

So we use

<params>
 <param>
  <value>
   <struct>
    <member>
     <name>param1_name</name>
     <value>param1_value</param>
    </member>
    <member>
     <name>param2_name</name>
     <value>
      <boolean>0</boolean>
     </param>
    </member>
   </struct>
  </value>
 </param>
</params>

instead of

<params>
 <param>
  <value>param1</value>
 </param>
 <param>
  <value>param2</value>
 </param>
</params>

This gives us more flexibility.

Methods

Here they are:

vg.test

Simple and plain test method

Parameters

  • Random Whatever you like

Response

  • status str 'ok'
  • data struct of the parameters you sent

vg.testApiKey

Test if your API key is valid

Parameters

  • apikey str required Your API key

Response on success

  • status str 'ok'

Response on error

  • status str 'error'
  • errorcode int error code
  • errormsg str error message

vg.i18n.getLanguages

List available languages

Parameters

  • apikey str required Your API key

Response on success

  • status str 'ok'
  • data struct of available languages, each element is a struct of
    • name str The Languages name in the language itself (Example deutsch for german language)
    • identifier str The two-letter identifier for the language, needed as param in most methods.

Response on error

  • status: str 'error'
  • errorcode int error code
  • errormsg str error message

vg.i18n.guessLanguage

Guess best language by HTTP Accept-Language request header

Parameters

  • apikey str required Your API key

Response on success

  • status str 'ok'
  • data struct of the guessed language, contains
    • name str The Languages name in the language itself (Example deutsch for german language)
    • identifier str The two-letter identifier for the language, needed as param in most methods.

Response on error

  • status: str 'error'
  • errorcode int error code
  • errormsg str error message

vg.browse.listCountries

List all countries which have known places

Parameters

  • apikey str required Your API key
  • lang str required Two-letter language code (Example: en)

Response on success

  • status str 'ok'
  • data struct of countries, each element is a struct of

Response on error

  • status: str 'error'
  • errorcode int error code
  • errormsg str error message

vg.browse.listCities

List all Cities of a Country which have known places

Parameters

  • apikey str required Your API key
  • lang str required Two-letter language code (Example: en)
  • country str required Country identifier (Example: germany)

Response on success

  • status str 'ok'
  • data struct of cities, each element is a struct of
    • name str The citys name in given language
    • identifier str Identifier for that city, needed in vg.browse.listPlacesByCity
    • count int Number of places for that city

Response on error

  • status: str 'error'
  • errorcode int error code
  • errormsg str error message

vg.browse.listPlacesByCity

List all places in a city

Parameters

  • apikey str required Your API key
  • lang str required Two-letter language code (Example: en)
  • city str required City identifier (Example: berlin)
  • country str recommended Country identifier as given in vg.browse.listCountries (Example: germany)
  • verbose array optional Show verbose info, may contain:
    • rating return average rating
    • submitter return submitter
    • address return address
    • city return city
    • country return country
    • coords return a struct of coords

Response on success

  • status str 'ok'
  • data struct of places, each element is a struct of
    • name str The places name
    • identifier str Identifier for that place, needed in vg.place.getInfo, vg.place.getImage and vg.place.getComments
    • verbose struct of optional verbose information
      • rating double average rating
      • submitter str submitter
      • address str address
      • city str city
      • country str country name
      • coords struct coords, contains
        • lat double latitude
        • lon double longitude

Response on error

  • status: str 'error'
  • errorcode int error code
  • errormsg str error message

vg.browse.listPlacesByCountry

List all places in a country

Parameters

  • apikey str required Your API key
  • lang str required Two-letter language code (Example: en)
  • country str required Country identifier as given in vg.browse.listCountries (Example: germany)
  • verbose array optional Show verbose info, may contain:
    • rating return average rating
    • submitter return submitter
    • address return address
    • city return city
    • country return country
    • coords return a struct of coords

Response on success

  • status str 'ok'
  • data struct of places, each element is a struct of
    • name str The places name
    • identifier str Identifier for that place, needed in vg.place.getInfo, vg.place.getImage and vg.place.getComments
    • verbose struct of optional verbose information
      • rating double average rating
      • submitter str submitter
      • address str address
      • city str city
      • country str country name
      • coords struct coords, contains
        • lat double latitude
        • lon double longitude

Response on error

  • status: str 'error'
  • errorcode int error code
  • errormsg str error message

vg.place.getInfo

Get info for a place

Parameters

  • apikey str required Your API key
  • lang str required Two-letter language code (Example: en)
  • place str required Place identifier as given in vg.browse.listPlaces* methods (Example: vleischerei)

Response on success

  • status str 'ok'
  • data struct of
    • name str Name
    • identifier str Identifier
    • address str Address
    • city str City
    • country str Country
    • description str Description or bool false
    • open str Open hours or bool false
    • contact struct of
      • phone str Phone number or bool false
      • fax str Fax number or bool false
      • www str Website URL or bool false
      • email str Email address od bool false
    • orientation str orientation, may contain
      • vegan Vegan only
      • vegan_freegan Vegan and Freegan only
      • freegan Freegan only
      • vegetarian Vegetarian, but vegan offers
      • omnivor Conventinal, but vegan offers
    • coords Coordinates, struct of
      • lat double latitude
      • lon double longitude
    • submitter str Submitter identifier
    • rating struct of
      • votes int Number of votes
      • rating double Average rating or bool false
    • photo bool There is a picture

Response on error

  • status: str 'error'
  • errorcode int error code
  • errormsg str error message

vg.place.getImage

Get image for a place. The max width is 800 px. Widths above 800 px throw an error.

Parameters

  • apikey str required Your API key
  • lang str required Two-letter language code (Example: en)
  • place str required Place identifier as given in vg.browse.listPlaces* methods (Example: vleischerei)
  • width int required Width (px)
  • returnmethod int required Return method, set
    • 0 for an URL str

Response on success

  • status str 'ok'
  • data struct of
    • url str URL, for returnmethod = 0

Response on error

  • status: str 'error'
  • errorcode int error code
  • errormsg str error message

vg.place.getComments

Get comments for a place

Parameters

  • apikey str required Your API key
  • lang str required Two-letter language code (Example: en)
  • place str required Place identifier as given in vg.browse.listPlaces* methods (Example: vleischerei)

Response on success

  • status str 'ok'
  • data array of comments, each element is a struct of
    • submitter str Submitter identifier
    • date dateTime.iso8601 Date
    • text str Comment text

Response on error

  • status: str 'error'
  • errorcode int error code
  • errormsg str error message

vg.search.byCoords

List places in a distance perimeter determined by a set of coordinates

Parameters

  • apikey str required Your API key
  • lang str required Two-letter language code (Example: en)
  • query struct required struct of:
    • lon double required Longitude
    • lat double required Latitude
    • radius double required Radius in km (yes, we use metrics and only metrics!), max 250, in future result may be cut down to a subset of the nearest results.
  • verbose array optional Show verbose info, may contain:
    • rating return average rating
    • submitter return submitter
    • address return address
    • city return city
    • country return country

Response on success

  • status str 'ok'
  • data struct of results, each element is a struct of
    • identifier str Identifier for that place, needed in vg.place.getInfo, vg.place.getImage and vg.place.getComments
    • name str The places name
    • distance double Distance between query and result coords in km (Metrics!)
    • coords struct coords, contains
      • lat double latitude
      • lon double longitude
    • verbose struct of optional verbose information
      • rating double average rating
      • submitter str submitter
      • address str address
      • city str city
      • country str country name

Response on error

  • status: str 'error'
  • errorcode int error code
  • errormsg str error message