MeLo API Explorer

API Method

/[user]/history

The stays in a user's location history can be accessed by date range, bounding box, or tag. This method returns a collection of stays from the user's location history that meet the specified criteria. None of the parameters are required. By default this method returns the user's most recent stays from the last 7 days. The response is a collection of stays (max 1000) during the specified period of time, ordered in descending order by datetime.

HTTP Verb(s)

  • GET

Parameters

  • start_date (optional)
    used with end_date to specify date range to filter stays. Format is YYYY-MM-DD
  • end_date (optional)
    used with start_date to specify date range to filter stays. Format is YYYY-MM-DD.
  • tag (optional)
    id of a tag used to select stays (Not Implemented)
  • bounds_ne (optional)
    list containing the latitude and longitude coordinates of the northeast corner of the bounding box
  • bounds_sw (optional)
    list containing the latitude and longitude coordinates of the southwest corner of the bounding box

/where

Geocodes or reverse-geocodes using the authenticating user's vocabulary and history.

HTTP Verb(s)

  • GET

Parameters

  • tag_id (optional)
    The id of the tag to geocode.
  • name (optional)
    The human-readable name to geocode. (Not implemented.)
  • lat (optional)
    The latitude of the point to reverse-geocode.
  • lon (optional)
    The longitude of the point to reverse-geocode.

/rules

Returns all rules for the authenticated user.

HTTP Verb(s)

  • GET

Parameters

/rule

Create a new rule for the authenticated user. Returns the new ID when successful.

HTTP Verb(s)

  • POST

Parameters

  • level (optional)
    The level of detail of information to be shared (or hidden) under this rule. Should be one of the canonical set of levels: everything, coordinates, name, category, activity, city, or nothing.
  • recipients (optional)
    A comma-separated list of email addresses identifying people that should be allowed (or disallowed) by a the rule. Optional, but one of recipients, group and everyone must be provided.
  • group (optional)
    The ID of a group belonging to the calling user, with whom location updates will be shared (or hidden). Optional, but one of recipients, group and everyone must be provided.
  • everyone (optional)
    Whether the rule should apply to Everyone (all MeLo users, and potentially everyone on the Internet). False by default. If true, don't set the group or recipients parameters.
  • end_time (optional)
    If the rule should expire at a certain time, this field should have the end time in the format: "2009-11-29 03:17 PM". If the rule has an expiration time, it may not also have a tag condition.
  • tag (optional)
    The ID of a tag limiting when this rule should apply. If the rule has an expiration time, it may not also have a tag condition.
  • allow (optional)
    Whether the rule is defining what kind of information to share or what kind of information to hide. True by default. If false, level will be set to 'nothing' if it isn't specified explicitly (this will hide all levels of information).
  • push (optional)
    Whether the rule defines information that should be pushed to the recipients. False by default.

/rule/[id]

Delete the specified rule for the authenticated user.

HTTP Verb(s)

  • DELETE

Parameters

/groups

Returns a list of the groups for the authenticated user.

HTTP Verb(s)

  • GET

Parameters

  • with_contacts (optional)
    true or false - whether MeLo should return the group members' email addresses as well as the name of each group.

/contacts

Returns a list of all the contacts (email addresses) for the authenticated user.

HTTP Verb(s)

  • GET

Parameters

/[user]/where

Returns the current location of the specified user. The returned location description will depend on rules set by the specified user for the requesting user.

HTTP Verb(s)

  • GET

Parameters

  • user_initiated
    whether a user initiated this request. This must be either "true" or "false". If "false", only data that the subject has pushed will be available.

/group/[id]/where

Returns the current location of the users in the specified group. The returned location descriptions will depend on rules set by the specified users for the requesting user.

HTTP Verb(s)

  • GET

Parameters

  • user_initiated
    whether a user initiated this request. This must be either "true" or "false". If "false", only data that the subject has pushed will be available.

/stay

Adds a stay for the particular user.

HTTP Verb(s)

  • POST

Parameters

  • lat
    Latitude coordinate of stay
  • lon
    Longitude coordinate of stay
  • start_time
    Start time of stay. Format is YYYY-MM-DD HH:MM:SS (timezone?)
  • end_time
    End time of stay. Format is YYYY-MM-DD HH:MM:SS (timezone?)
  • description
    Description or name of stay

/stay/[id]

GET Returns a single stay specified by the ID provided. PUT Updates the specified stay with a new start time, end time, or location. DELETE Deleted the specified stay, all its associated points and all its applied tags.

HTTP Verb(s)

  • GET
  • PUT
  • DELETE

Parameters

  • lat (optional)
    Can be used in a PUT operation to change the latitude coordinate of stay (Not implemented)
  • lon (optional)
    Can be used in a PUT operation to change the longitude coordinate of stay (Not implemented)
  • start_date (optional)
    Can be used in a PUT operation to change the start time of a stay. Format is YYYY-MM-DD HH:MM:SS (timezone?)
  • end_date (optional)
    Can be used in a PUT operation to change the end time of a stay. Format is YYYY-MM-DD HH:MM:SS (timezone?)
  • description (optional)
    Can be used in a PUT operation to change the displayed description for the location

/stay/[id]/tag

Adds a tag to a stay.

HTTP Verb(s)

  • POST

Parameters

  • title
    The name of the tag being added.
  • source
    Where the tag is from (ex. could be 'Yahoo API' if suggested, or 'personal' for user-created)
  • source_method
    What method was called to suggest tag (ex. could be 'geosearch-api' for suggested, or 'personal for user-created tags)
  • our_type
    What the MeLo type for the tag is (either 'category', 'activity', 'geographic', 'venue' or 'personal')
  • service_type
    Category of the tag for the location (ex. 'business' or 'intersection')
  • guid (optional)
    Unique identifier for the tag if it's from an external API

/stay/[stay_id]/tag/[tag_id]

Deletes a specific tag specified by the tag_id for a single stay specified by the stay_id provided.

HTTP Verb(s)

  • DELETE

Parameters

/stay/[id]/tags/applied

Returns all tags associated with a single stay specified by the ID provided.

HTTP Verb(s)

  • GET

Parameters

/stay/[id]/tags/suggested

Returns all suggested tags for the stay specified by the ID.

HTTP Verb(s)

  • GET

Parameters

/stay/[id]/tags/all

Returns all tags (both suggested and associated) for the stay specified by the ID.

HTTP Verb(s)

  • GET

Parameters

/point

Adds a point to the user's location information. The point is automatically added to the appropriate stay.

HTTP Verb(s)

  • POST

Parameters

  • lat
    Latitude coordinate of the location point
  • lon
    Longitude coordinate of the location point
  • timestamp
    Timestamp of when location was recorded, in the format YYYY-MM-DD HH:MM:SS
  • accuracy (optional)
    Accuracy in meters of recorded coordinates
  • timezone (optional)
    Timezone used to record the timestamp
  • reverse_geocode (optional)
    Name for the place that is derived from the given coordinate pair

/tags

Returns a list of potential tags for the authenticating user, optionally filtered by type (name, category, description, activity). This can be useful for auto-completion.

HTTP Verb(s)

  • GET

Parameters

  • type (optional)
    Type to filter on (one of: name, category, description, activity)

/tag/[id]

Returns information about a tag in its general usage. How popular is it? Where is it from? What kind of tag is it?

HTTP Verb(s)

  • GET

Parameters

/tag/[tag_title]

Returns information about a tag in its general usage. How popular is it? Where is it from? What kind of tag is it? (Not implemented)

HTTP Verb(s)

  • GET

Parameters

Terms of Service

Both MeLo and the MeLo API are pre-release software: the functionality of these API methods is absolutely not guaranteed, bugs are expected and functionality will change and disappear without notice.

By using this API, you agree to access MeLo user data only on the user's behalf, protect the user's privacy and not harass the user or misappropriate their data. Before you access a user's data, you must provide a clear, conspicuous and up-front disclosure of how your application will use their data. You also agree to use the API as we have intended it: not hitting our poor servers more than is reasonable (determined at our discretion) and complying with all documentation, including policy fields like user_initiated. If you have any questions, please ask.