spacedirectory.org

API Documentation

It's highly recommended to use the explicit specified fields from the reference. If you need other fields additionally, please make a change request. Or prefix custom fields with ext_ to make it clear the field is not part of the documented API. Consumers are not obligated to interpret any custom fields.

Most types are not nullable. That means that they may not contain the value "null", but they may be left away if they're not required.

  • api

    (string) required
    Details

    The version of SpaceAPI your endpoint uses

    Valid values

    0.13

  • space

    (string) required
    Details

    The name of your space

  • logo

    (string) required
    Details

    URL to your space logo

  • url

    (string) required
    Details

    URL to your space website

  • location

    (object) required
    Details

    Position data such as a postal address or geographic coordinates

    Nested object properties

    • address

      (string)
      Details

      The postal address of your space (street, block, housenumber, zip code, city, whatever you usually need in your country, and the country itself).
      Examples:

      • Netzladen e.V., Breite Straße 74, 53111 Bonn, Germany

    • lat

      (number) required
      Details

      Latitude of your space location, in degree with decimal places. Use positive values for locations north of the equator, negative values for locations south of equator.

    • lon

      (number) required
      Details

      Longitude of your space location, in degree with decimal places. Use positive values for locations west of Greenwich, and negative values for locations east of Greenwich.

  • spacefed

    (object)
    Details

    A flag indicating if the hackerspace uses SpaceFED, a federated login scheme so that visiting hackers can use the space WiFi with their home space credentials.

    Nested object properties

    • spacenet

      (boolean) required
      Details

      See the wiki.

    • spacesaml

      (boolean) required
      Details

      See the wiki.

    • spacephone

      (boolean) required
      Details

      See the wiki.

  • cam

    (array of string)
    Details

    URL(s) of webcams in your space

    Minimum number of items

    1

    Nested array items

    string
  • stream

    (object)
    Details

    A mapping of stream types to stream URLs.If you use other stream types make a change request or prefix yours with ext_ .

    Nested object properties

    • m4

      (string)
      Details

      Your mpg stream URL. Example: {"mp4": "http//example.org/stream.mpg"}

    • mjpeg

      (string)
      Details

      Your mjpeg stream URL. Example: {"mjpeg": "http://example.org/stream.mjpeg"}

    • ustream

      (string)
      Details

      Your ustream stream URL. Example: {"ustream": "http://www.ustream.tv/channel/hackspsps"}

  • state

    (object) required
    Details

    A collection of status-related data: actual open/closed status, icons, last change timestamp etc.

    Nested object properties

    • open

      (boolean) required nullable
      Details

      A flag which indicates if the space is currently open or closed. The state 'undefined' can be achieved by assigning this field the value 'null' (without the quotes). In most (all?) programming languages this is evaluated to false so that no app should break

    • lastchange

      (number)
      Details

      The Unix timestamp when the space status changed most recently

    • trigger_person

      (string)
      Details

      The person who lastly changed the state e.g. opened or closed the space.

    • message

      (string)
      Details

      An additional free-form string, could be something like 'open for public', 'members only' or whatever you want it to be

    • icon

      (object)
      Details

      Icons that show the status graphically

      Nested object properties

      • open

        (string) required
        Details

        The URL to your customized space logo showing an open space

      • closed

        (string) required
        Details

        The URL to your customized space logo showing a closed space

  • events

    (array of object)
    Details

    Events which happened recently in your space and which could be interesting to the public, like 'User X has entered/triggered/did something at timestamp Z'

    Nested array items

    • name

      (string) required
      Details

      Name or other identity of the subject (e.g. J. Random Hacker, fridge, 3D printer, …)

    • type

      (string) required
      Details

      Action (e.g. check-in, check-out, finish-print, …). Define your own actions and use them consistently, canonical actions are not (yet) specified

    • timestamp

      (number) required
      Details

      Unix timestamp when the event occured

    • extra

      (string)
      Details

      A custom text field to give more information about the event

  • contact

    (object) required
    Details

    Contact information about your space. You must define at least one which is in the list of allowed values of the issue_report_channels field.

    Nested object properties

    • phone

      (string)
      Details

      Phone number, including country code with a leading plus sign. Example: +1 800 555 4567

    • sip

      (string)
      Details

      URI for Voice-over-IP via SIP. Example: sip:yourspace@sip.example.org

    • keymasters

      (array of object)
      Details

      Persons who carry a key and are able to open the space upon request. One of the fields irc_nick, phone, email or twitter must be specified.

      Minimum number of items

      1

      Nested array items

      • name

        (string)
        Details

        Real name

      • irc_nick

        (string)
        Details

        Contact the person with this nickname directly in irc if available. The irc channel to be used is defined in the contact/irc field.

      • phone

        (string)
        Details

        Example: ['+1 800 555 4567','+1 800 555 4544']

      • email

        (string)
        Details

        Email address which can be base64 encoded.

      • twitter

        (string)
        Details

        Twitter username with leading @.

    • irc

      (string)
      Details

      URL of the IRC channel, in the form irc://example.org/#channelname

    • twitter

      (string)
      Details

      Twitter handle, with leading @

    • facebook

      (string)
      Details

      Facebook account URL.

    • google

      (object)
      Details

      Google services.

      Nested object properties

      • plus

        (string)
        Details

        Google plus URL.

    • identica

      (string)
      Details

      Identi.ca or StatusNet account, in the form yourspace@example.org

    • foursquare

      (string)
      Details

      Foursquare ID, in the form 4d8a9114d85f3704eab301dc.

    • email

      (string)
      Details

      E-mail address for contacting your space. If this is a mailing list consider to use the contact/ml field.

    • ml

      (string)
      Details

      The e-mail address of your mailing list. If you use Google Groups then the e-mail looks like your-group@googlegroups.com.

    • jabber

      (string)
      Details

      A public Jabber/XMPP multi-user chatroom in the form chatroom@conference.example.net

    • issue_mail

      (string)
      Details

      A seperate email address for issue reports (see the issue_report_channels field). This value can be Base64-encoded.

  • issue_report_channels

    (array of string) required
    Details

    This array defines all communication channels where you want to get automated issue reports about your SpaceAPI endpoint from the revalidator. This field is meant for internal usage only and it should never be consumed by any app. At least one channel must be defined. Please consider that when using ml the mailing list moderator has to moderate incoming emails or add the sender email to the subscribers. If you don't break your SpaceAPI implementation you won't get any notifications ;-)

    Minimum number of items

    1

    Nested array items

    string
  • sensors

    (object)
    Details

    Data of various sensors in your space (e.g. temperature, humidity, amount of Club-Mate left, …). The only canonical property is the temp property, additional sensor types may be defined by you. In this case, you are requested to share your definition for inclusion in this specification.

    Nested object properties

    • temperature

      (array of object)
      Details

      Temperature sensor. To convert from one unit of temperature to another consider Wikipedia.

      Nested array items

      • value

        (number) required
        Details

        The sensor value

      • unit

        (string) required
        Details

        The unit of the sensor value.

        Valid values

        °C | °F | K | °De | °N | °R | °Ré | °Rø

      • location

        (string) required
        Details

        The location of your sensor such as Outside, Inside, Ceiling, Roof or Room 1.

      • name

        (string)
        Details

        This field is an additional field to give your sensor a name. This can be useful if you have multiple sensors in the same location.

      • description

        (string)
        Details

        An extra field that you can use to attach some additional information to this sensor instance.

    • door_locked

      (array of object)
      Details

      Sensor type to indicate if a certain door is locked.

      Nested array items

      • value

        (boolean) required
        Details

        The sensor value

      • location

        (string) required
        Details

        The location of your sensor such as front door, chill room or lab.

      • name

        (string)
        Details

        This field is an additional field to give your sensor a name. This can be useful if you have multiple sensors in the same location.

      • description

        (string)
        Details

        An extra field that you can use to attach some additional information to this sensor instance.

    • barometer

      (array of object)
      Details

      Barometer sensor

      Nested array items

      • value

        (number) required
        Details

        The sensor value

      • unit

        (string) required
        Details

        The unit of the sensor value. You should always define the unit though if the sensor is a flag of a boolean type then you can of course omit it.

        Valid values

        hPA

      • location

        (string) required
        Details

        The location of your sensor such as Outside, Inside, Ceiling, Roof or Room 1.

      • name

        (string)
        Details

        This field is an additional field to give your sensor a name. This can be useful if you have multiple sensors in the same location.

      • description

        (string)
        Details

        An extra field that you can use to attach some additional information to this sensor instance.

    • radiation

      (object)
      Details

      Compound radiation sensor. Check this resource.

      Nested object properties

      • alpha

        (array of object)
        Details

        An alpha sensor

        Nested array items

        • value

          (number) required
          Details

          Observed counts per minute (ocpm) or actual radiation value. If the value are the observed counts then the dead_time and conversion_factor fields must be defined as well. CPM formula:

          cpm = ocpm ( 1 + 1 / (1 - ocpm x dead_time) )
          Conversion formula:
          µSv/h = cpm x conversion_factor

        • unit

          (string) required
          Details

          Choose the appropriate unit for your radiation sensor instance.

          Valid values

          cpm | r/h | µSv/h | mSv/a | µSv/a

        • dead_time

          (number)
          Details

          The dead time in µs. See the description of the value field to see how to use the dead time.

        • conversion_factor

          (number)
          Details

          The conversion from the cpm unit to another unit hardly depends on your tube type. See the description of the value field to see how to use the conversion factor. Note: only trust your manufacturer if it comes to the actual factor value. The internet seems full of wrong copy & pastes, don't even trust your neighbour hackerspace. If in doubt ask the tube manufacturer.

        • location

          (string)
          Details

          The location of your sensor such as Outside, Inside, Ceiling, Roof or Room 1.

        • name

          (string)
          Details

          This field is an additional field to give your sensor a name. This can be useful if you have multiple sensors in the same location.

        • description

          (string)
          Details

          An extra field that you can use to attach some additional information to this sensor instance.

      • beta

        (array of object)
        Details

        A beta sensor

        Nested array items

        • value

          (number) required
          Details

          Observed counts per minute (ocpm) or actual radiation value. If the value are the observed counts then the dead_time and conversion_factor fields must be defined as well. CPM formula:

          cpm = ocpm ( 1 + 1 / (1 - ocpm x dead_time) )
          Conversion formula:
          µSv/h = cpm x conversion_factor

        • unit

          (string) required
          Details

          Choose the appropriate unit for your radiation sensor instance.

          Valid values

          cpm | r/h | µSv/h | mSv/a | µSv/a

        • dead_time

          (number)
          Details

          The dead time in µs. See the description of the value field to see how to use the dead time.

        • conversion_factor

          (number)
          Details

          The conversion from the cpm unit to another unit hardly depends on your tube type. See the description of the value field to see how to use the conversion factor. Note: only trust your manufacturer if it comes to the actual factor value. The internet seems full of wrong copy & pastes, don't even trust your neighbour hackerspace. If in doubt ask the tube manufacturer.

        • location

          (string)
          Details

          The location of your sensor such as Outside, Inside, Ceiling, Roof or Room 1.

        • name

          (string)
          Details

          This field is an additional field to give your sensor a name. This can be useful if you have multiple sensors in the same location.

        • description

          (string)
          Details

          An extra field that you can use to attach some additional information to this sensor instance.

      • gamma

        (array of object)
        Details

        A gamma sensor

        Nested array items

        • value

          (number) required
          Details

          Observed counts per minute (ocpm) or actual radiation value. If the value are the observed counts then the dead_time and conversion_factor fields must be defined as well. CPM formula:

          cpm = ocpm ( 1 + 1 / (1 - ocpm x dead_time) )
          Conversion formula:
          µSv/h = cpm x conversion_factor

        • unit

          (string) required
          Details

          Choose the appropriate unit for your radiation sensor instance.

          Valid values

          cpm | r/h | µSv/h | mSv/a | µSv/a

        • dead_time

          (number)
          Details

          The dead time in µs. See the description of the value field to see how to use the dead time.

        • conversion_factor

          (number)
          Details

          The conversion from the cpm unit to another unit hardly depends on your tube type. See the description of the value field to see how to use the conversion factor. Note: only trust your manufacturer if it comes to the actual factor value. The internet seems full of wrong copy & pastes, don't even trust your neighbour hackerspace. If in doubt ask the tube manufacturer.

        • location

          (string)
          Details

          The location of your sensor such as Outside, Inside, Ceiling, Roof or Room 1.

        • name

          (string)
          Details

          This field is an additional field to give your sensor a name. This can be useful if you have multiple sensors in the same location.

        • description

          (string)
          Details

          An extra field that you can use to attach some additional information to this sensor instance.

      • beta_gamma

        (array of object)
        Details

        A sensor which cannot filter beta and gamma radiation seperately.

        Nested array items

        • value

          (number) required
          Details

          Observed counts per minute (ocpm) or actual radiation value. If the value are the observed counts then the dead_time and conversion_factor fields must be defined as well. CPM formula:

          cpm = ocpm ( 1 + 1 / (1 - ocpm x dead_time) )
          Conversion formula:
          µSv/h = cpm x conversion_factor

        • unit

          (string) required
          Details

          Choose the appropriate unit for your radiation sensor instance.

          Valid values

          cpm | r/h | µSv/h | mSv/a | µSv/a

        • dead_time

          (number)
          Details

          The dead time in µs. See the description of the value field to see how to use the dead time.

        • conversion_factor

          (number)
          Details

          The conversion from the cpm unit to another unit hardly depends on your tube type. See the description of the value field to see how to use the conversion factor. Note: only trust your manufacturer if it comes to the actual factor value. The internet seems full of wrong copy & pastes, don't even trust your neighbour hackerspace. If in doubt ask the tube manufacturer.

        • location

          (string)
          Details

          The location of your sensor such as Outside, Inside, Ceiling, Roof or Room 1.

        • name

          (string)
          Details

          This field is an additional field to give your sensor a name. This can be useful if you have multiple sensors in the same location.

        • description

          (string)
          Details

          An extra field that you can use to attach some additional information to this sensor instance.

    • humidity

      (array of object)
      Details

      Humidity sensor

      Nested array items

      • value

        (number) required
        Details

        The sensor value

      • unit

        (string) required
        Details

        The unit of the sensor value. You should always define the unit though if the sensor is a flag of a boolean type then you can of course omit it.

        Valid values

        %

      • location

        (string) required
        Details

        The location of your sensor such as Outside, Inside, Ceiling, Roof or Room 1.

      • name

        (string)
        Details

        This field is an additional field to give your sensor a name. This can be useful if you have multiple sensors in the same location.

      • description

        (string)
        Details

        An extra field that you can use to attach some additional information to this sensor instance.

    • beverage_supply

      (array of object)
      Details

      How much Mate and beer is in your fridge?

      Nested array items

      • value

        (number) required
        Details

        The sensor value

      • unit

        (string) required
        Details

        The unit, either btl for bottles or crt for crates.

        Valid values

        btl | crt

      • location

        (string)
        Details

        The location of your sensor such as Room 1 or Room 2 or Room 3, Roof or Room 1.

      • name

        (string)
        Details

        This field is an additional field to give your sensor a name. This can be useful if you have multiple sensors in the same location.

      • description

        (string)
        Details

        An extra field that you can use to attach some additional information to this sensor instance.

    • power_consumption

      (array of object)
      Details

      The power consumption of a specific device or of your whole space.

      Nested array items

      • value

        (number) required
        Details

        The sensor value

      • unit

        (string) required
        Details

        The unit of the sensor value. You should always define the unit though if the sensor is a flag of a boolean type then you can of course omit it.

        Valid values

        mW | W | VA

      • location

        (string) required
        Details

        The location of your sensor such as Outside, Inside, Ceiling, Roof or Room 1.

      • name

        (string)
        Details

        This field is an additional field to give your sensor a name. This can be useful if you have multiple sensors in the same location.

      • description

        (string)
        Details

        An extra field that you can use to attach some additional information to this sensor instance.

    • wind

      (array of object)
      Details

      Your wind sensor.

      Nested array items

      • properties

        (object) required
        Details

        Nested object properties

        • speed

          (object) required
          Details

          Nested object properties

          • value

            (number) required
            Details

            The sensor value

          • unit

            (string) required
            Details

            The unit of the sensor value. You should always define the unit though if the sensor is a flag of a boolean type then you can of course omit it.

            Valid values

            m/s | km/h | kn

        • gust

          (object) required
          Details

          Nested object properties

          • value

            (number) required
            Details

            The sensor value

          • unit

            (string) required
            Details

            The unit of the sensor value. You should always define the unit though if the sensor is a flag of a boolean type then you can of course omit it.

            Valid values

            m/s | km/h | kn

        • direction

          (object) required
          Details

          The wind direction in degrees. Use this mapping to convert the degrees into a string.

          Nested object properties

          • value

            (number) required
            Details

            The sensor value

          • unit

            (string) required
            Details

            The unit of the sensor value. You should always define the unit though if the sensor is a flag of a boolean type then you can of course omit it.

            Valid values

            °

        • elevation

          (object) required
          Details

          Height above mean sea level.

          Nested object properties

          • value

            (number) required
            Details

            The sensor value

          • unit

            (string) required
            Details

            The unit of the sensor value. You should always define the unit though if the sensor is a flag of a boolean type then you can of course omit it.

            Valid values

            m

      • location

        (string) required
        Details

        The location of your sensor such as Outside, Inside, Ceiling, Roof or Room 1.

      • name

        (string)
        Details

        This field is an additional field to give your sensor a name. This can be useful if you have multiple sensors in the same location.

      • description

        (string)
        Details

        An extra field that you can use to attach some additional information to this sensor instance.

    • network_connections

      (array of object)
      Details

      This sensor type is to specify the currently active ethernet or wireless network devices. You can create different instances for each network type.

      Nested array items

      • type

        (string)
        Details

        This field is optional but you can use it to the network type such as wifi or cable. You can even expose the number of spacenet-authenticated connections.

        Valid values

        wifi | cable | spacenet

      • value

        (number) required
        Details

        The amount of network connections.

      • machines

        (array of object)
        Details

        The machines that are currently connected with the network.

        Nested array items

        • name

          (string)
          Details

          The machine name.

        • mac

          (string) required
          Details

          The machine's MAC address of the format D3:3A:DB:EE:FF:00.

      • location

        (string)
        Details

        The location of your sensor such as Outside, Inside, Ceiling, Roof or Room 1.

      • name

        (string)
        Details

        This field is an additional field to give your sensor a name. This can be useful if you have multiple sensors in the same location.

      • description

        (string)
        Details

        An extra field that you can use to attach some additional information to this sensor instance.

    • account_balance

      (array of object)
      Details

      How rich is your hackerspace?

      Nested array items

      • value

        (number) required
        Details

        How much?

      • unit

        (string) required
        Details

        What's the currency? If your currency is missing open a new issue and request the addition of your currency according ISO 4217.

        Valid values

        BTC | EUR | USD | GBP

      • location

        (string)
        Details

        If you have more than one account you can use this field to specify where it is.

      • name

        (string)
        Details

        Give your sensor instance a name.

      • description

        (string)
        Details

        An extra field that you can use to attach some additional information to this sensor instance.

    • total_member_count

      (array of object)
      Details

      Specify the number of space members.

      Nested array items

      • value

        (number) required
        Details

        The amount of your space members.

      • location

        (string)
        Details

        Specify the location if your hackerspace has different departments (for whatever reason). This field is for one department. Every department should have its own sensor instance.

      • name

        (string)
        Details

        You can use this field to specify if this sensor instance counts active or inactive members.

      • description

        (string)
        Details

        An extra field that you can use to attach some additional information to this sensor instance.

    • people_now_present

      (array of object)
      Details

      Specify the number of people that are currently in your space. Optionally you can define a list of names.

      Nested array items

      • value

        (number) required
        Details

        The amount of present people.

      • location

        (string)
        Details

        If you use multiple sensor instances for different rooms, use this field to indicate the location.

      • name

        (string)
        Details

        Give this sensor a name if necessary at all. Use the location field for the rooms. This field is not intended to be used for names of hackerspace members. Use the field 'names' instead.

      • names

        (array of string)
        Details

        List of hackerspace members that are currently occupying the space.

        Minimum number of items

        1

        Nested array items

        string
      • description

        (string)
        Details

        An extra field that you can use to attach some additional information to this sensor instance.

  • feeds

    (object)
    Details

    Feeds where users can get updates of your space

    Nested object properties

    • blog

      (object)
      Details

      Nested object properties

      • type

        (string)
        Details

        Type of the feed, for example rss, atom, ical

      • url

        (string) required
        Details

        Feed URL

    • wiki

      (object)
      Details

      Nested object properties

      • type

        (string)
        Details

        Type of the feed, for example rss, atom, ical

      • url

        (string) required
        Details

        Feed URL

    • calendar

      (object)
      Details

      Nested object properties

      • type

        (string)
        Details

        Type of the feed, for example rss, atom, ical

      • url

        (string) required
        Details

        Feed URL

    • flickr

      (object)
      Details

      Nested object properties

      • type

        (string)
        Details

        Type of the feed, for example rss, atom, ical

      • url

        (string) required
        Details

        Feed URL

  • cache

    (object)
    Details

    Specifies options about caching of your SpaceAPI endpoint. Use this if you want to avoid hundreds/thousands of application instances crawling your status.

    Nested object properties

    • schedule

      (string) required
      Details

      Cache update cycle. This field must match the basic regular expression ^[mhd]\.[0-9]{2}$, where the first field specifies a unit of time (m for 1 minute, h for 1 hour, d for 1 day), and the second field specifies how many of this unit should be skipped between updates. For example, m.10 means one updates every 10 minutes, h.03 means one update every 3 hours, and d.01 means one update every day.

      Valid values

      m.02 | m.05 | m.10 | m.15 | m.30 | h.01 | h.02 | h.04 | h.08 | h.12 | d.01

  • projects

    (array of string)
    Details

    Your project sites (links to GitHub, wikis or wherever your projects are hosted)

    Nested array items

    string
  • radio_show

    (array of object)
    Details

    A list of radio shows that your hackerspace might broadcast.

    Nested array items

    • name

      (string) required
      Details

      The name of the radio show.

    • url

      (string) required
      Details

      The stream URL which must end in a filename or a semicolon such as

      • http://signal.hackerspaces.org:8090/signal.mp3
      • http://85.214.64.213:8060/;

    • type

      (string) required
      Details

      The stream encoder.

      Valid values

      mp3 | ogg

    • start

      (string) required
      Details

      Specify the start time by using the ISO 8601 standard. This encodes the time as follows:

      • Combined date and time in UTC: 2013-06-10T10:00Z
      • Combined date and time in localtime with the timezone offset: 2013-06-10T12:00+02:00
      • Combined date and time in localtime with the timezone offset: 2013-06-10T07:00-03:00
      The examples refer all to the same time.

    • end

      (string) required
      Details

      Specify the end time by using the ISO 8601 standard. This encodes the time as follows:

      • Combined date and time in UTC: 2013-06-10T10:00Z
      • Combined date and time in localtime with the timezone offset: 2013-06-10T12:00+02:00
      • Combined date and time in localtime with the timezone offset: 2013-06-10T07:00-03:00
      The examples refer all to the same time.