Pinmaps.net API

About

Pinmaps.net is an online service that lets individuals easily search, save, share and quickly access their favorite locations on a map. Pinmaps.net allows you to create maps where you can add map points (push pins) to it. What makes this service stand out from other services is that you can save each map point with its own zoom level and map type.

We suggest that you get familiar with the Pinmaps.net service and understand the concepts behing it before attempting to use the API.

This API has been depricated and no longer in service.
We're dedicating our effort and development resounces to make Pinmaps.net service better every day.

What you need

In order to interact with the Pinmaps API you need to get a developer's API key and a user's API key. Every single call to the API requires four main credentials:
DeveloperApiLogin, DeveloperApiKey, Username, and UserApiKey.
Obtaining these four API Credentials is a three step process:

Your Developer's API key will allow you to interact with your own pinmaps account as well as to make calls to the Pinmaps API on behalf of other users. If you want to make API calls on behalf of other users you need to ask them for their user's API key.

Maps API Methods

Introduction

A map is a large area such as a city, a state, or a country that can hold many map points. You can create several maps with lots of map points to suit your needs.
Important: your map is like a container for your map points (push pins) See Sample Maps

GET v1/map

This method returns a single map object by map ID. The result does not include the map points.

Request URL
http://api.pinmaps.net/v1/map?id={id}&apiLogin={apiLogin}&developerKey={developerKey}&userName={userName}&userKey={userKey}
Parameters
apiLogin
required		 Developer's API login name
developerKey
required		 Developer's API Key
userName
required		 The username of the map owner
userKey
required		 The user's API key of the map owner
id
required		 The id of the map you want to retrieve
Json Response
    {"MapID":2444,
     "MapName":"USA Airports",
     "Latitude":"38.06539235133249",
     "Longitude":"-96.10839844375",
     "ZoomLevel":"5",
     "MapType":"G_PHYSICAL_MAP",
     "MapOwner":"PinUser",
     "CreatedOn":"2013-03-15T14:20:52.993",
     "ModifiedOn":"2013-03-15T14:20:52.993",
     "IsShared":false,
     "MapLogo":"pinmaps_logo_trans.png",
     "RssUrl":"",
     "FitToBounds":true,
     "IconZomIn":true,
     "Overlays":"",
     "Icon":{"IconID":1,
             "IconName":"dot-red.png",
             "IconShadow":"msmarker_shadow.png",
             "IconWidth":"32",
             "IconHeight":"32",
             "ShadowWidth":"59",
             "ShadowHeight":"32"}
    }

GET v1/maps

This method returns a collection of maps objects by username. The list does not include the map points.

Request URL
http://api.pinmaps.net/v1/maps?apiLogin={apiLogin}&developerKey={developerKey}&userName={userName}&userKey={userKey}
Parameters
apiLogin
required		 Developer's API login name
developerKey
required		 Developer's API Key
userName
required		 The username of the map owner
userKey
required		 The user's API key of the map owner
Json Response
    [{"MapID":2457,
      "MapName":"USA Customers",
      "Latitude":"38.06539235133249",
      "Longitude":"-96.10839844375",
      "ZoomLevel":"5",
      "MapType":"G_NORMAL_MAP",
      "MapOwner":"PinUser",
      "CreatedOn":"2013-03-15T21:21:56.6",
      "ModifiedOn":"2013-03-15T21:21:56.6",
      "IsShared":false,
      "MapLogo":"pinmaps_logo_trans.png",
      "RssUrl":"",
      "FitToBounds":true,
      "IconZomIn":true,
      "Overlays":"",
      "Icon":{"IconID":1,
              "IconName":"dot-red.png",
              "IconShadow":"msmarker_shadow.png",
              "IconWidth":"32",
              "IconHeight":"32",
              "ShadowWidth":"59",
              "ShadowHeight":"32"}
     },{"MapID":2444,
        "MapName":"USA Airports",
        "Latitude":"38.06539235133249",
        "Longitude":"-96.10839844375",
        "ZoomLevel":"5",
        "MapType":"G_PHYSICAL_MAP",
        "MapOwner":"PinUser",
        "CreatedOn":"2013-03-15T14:20:52.993",
        "ModifiedOn":"2013-03-15T14:20:52.993",
        "IsShared":false,"MapLogo":"pinmaps_logo_trans.png",
        "RssUrl":"",
        "FitToBounds":true,
        "IconZomIn":true,
        "Overlays":"",
        "Icon":{"IconID":1,
                "IconName":"dot-red.png",
                "IconShadow":"msmarker_shadow.png",
                "IconWidth":"32",
                "IconHeight":"32",
                "ShadowWidth":"59",
                "ShadowHeight":"32"}
    }]

POST v1/map/create

This method creates a single map on the selected MapZone and returns the created map object
Post format: json

Resource URL
http://api.pinmaps.net/v1/map/create.json
Parameters
DeveloperApiLogin
required		 Developer's API login name
DeveloperApiKey
required		 Developer's API Key
UserName
required		 The username of the map owner
UserApiKey
required		 The user's API key of the map owner
MapName
required		 Name of the map
MapType
optional		 The types of maps you can display.
Use only any of these values: ROADMAP, SATELLITE, HYBRID, TERRAIN
If not value or wrong value is supplied a ROADMAP will be used.
Map Types Definitions:
ROADMAP: displays the default road map view
SATELLITE: displays Google Earth satellite images
HYBRID: displays a mixture of normal and satellite views
TERRAIN: displays a physical map based on terrain information.
Json Response
    {"MapID":2463,
     "MapName":"USA Airports",
     "Latitude":"38.06539235133249",
     "Longitude":"-96.10839844375",
     "ZoomLevel":"5",
     "MapType":"G_NORMAL_MAP",
     "MapOwner":"PinUser",
     "CreatedOn":"2013-03-26T15:46:31.453",
     "ModifiedOn":null,
     "IsShared":false,
     "MapLogo":"pinmaps_logo_trans.png",
     "RssUrl":"",
     "FitToBounds":true,
     "IconZomIn":true,
     "Overlays":"",
     "Icon":{"IconID":1,
             "IconName":"dot-red.png",
             "IconShadow":"msmarker_shadow.png",
             "IconWidth":"32",
             "IconHeight":"32",
             "ShadowWidth":"59",
             "ShadowHeight":"32"}
    }

PUT v1/map/update

This method updates a single map and returns the updated map object
Put format: json

Resource URL
http://api.pinmaps.net/v1/map/update.json
Parameters
DeveloperApiLogin
required		 Developer's API login name
DeveloperApiKey
required		 Developer's API Key
UserName
required		 The username of the map owner
UserApiKey
required		 The user's API key of the map owner
MapID
required		 The id of the map you want to update
MapName
required		 Name of the map (current or new)
MapType
optional		 The types of maps you can display.
Use only any of these values: ROADMAP, SATELLITE, HYBRID, TERRAIN
If not value or wrong value is supplied a ROADMAP will be used.
Json Response
      { "MapID":2444,
        "MapName":"USA Airports",
        "Latitude":"38.06539235133249",
        "Longitude":"-96.10839844375",
        "ZoomLevel":"5",
        "MapType":"G_PHYSICAL_MAP",
        "MapOwner":"PinUser",
        "CreatedOn":"2013-03-15T14:20:52.993",
        "ModifiedOn":"2013-03-17T21:12:23.035",
        "IsShared":false,
        "MapLogo":"pinmaps_logo_trans.png",
        "RssUrl":"",
        "FitToBounds":true,
        "IconZomIn":true,
        "Overlays":"",
        "Icon":{ "IconID":1,
                 "IconName":"dot-red.png",
                 "IconShadow":"msmarker_shadow.png",
                 "IconWidth":"32",
                 "IconHeight":"32",
                 "ShadowWidth":"59",
                 "ShadowHeight":"32" }
      }

DELETE v1/map/destroy

This method deletes a single map object by map ID
Delete format: json

Resource URL
http://api.pinmaps.net/v1/map/destroy.json
Parameters
DeveloperApiLogin
required		 Developer's API login name
DeveloperApiKey
required		 Developer's API Key
UserName
required		 The username of the map owner
UserApiKey
required		 The user's API key of the map owner
MapID
required		 The id of the map you want to remove
Json Response
    {"MapID":2463,"UserName":"PinUser","PinsCount":14}

GET v1/maps/count

This method returns the total maps count by username.

Request URL
http://api.pinmaps.net/v1/maps/count?apiLogin={apiLogin}&developerKey={developerKey}&userName={userName}&userKey={userKey}
Parameters
apilogin
required		 Developer's API login name
developer key
required		 Developer's API Key
username
required		 The username of the map owner
usekey
required		 The user's API key of the map owner
Json Response
    {"UserName":"PinUser","Count":2}

Map Points API Methods

Introduction

A map point is a location on a map such as an address that is physically represented by an icon (marker). Many map points can be added to a single map.
Important: Each map point is an individual entity with it's own zoom level and map type. Sample Maps

GET v1/pin

This method returns a single map point object by map point ID.

Request URL
http://api.pinmaps.net/v1/pin?id={id}&apiLogin={apiLogin}&developerKey={developerKey}&userName={userName}&userKey={userKey}
Parameters
apilogin
required		 Developer's API login name
developer key
required		 Developer's API Key
username
required		 The username of the map owner
usekey
required		 The user's API key of the map owner
id
required		 The id of the map point you want to retrieve
Json Response
    {"MapPointID":5135,
     "MapID":2444,
     "UserName":"PinUser",
     "PointName":"Orlando International",
     "GeocodeAddress":"One Jeff Fuqua Blvd, Orlando, FL 32827, USA",
     "Latitude":"28.4316390",
     "Longitude":"-81.3082862",
     "ZoomLevel":"16",
     "MapType":"G_NORMAL_MAP",
     "PointInfo":"Main Airport hub where I take the flight to visit my clients",
     "DatePosted":"2013-03-15T14:38:54.51",
     "ModifiedOn":null,
     "LinkToGoogleMaps":"maps.google.com/maps?q=28.4316390,-81.3082862&t=m&z=16",
     "Label":"Newark",
     "LabelIsVisible":true,
     "Icon":{"IconID":1,
             "IconName":"dot-red.png",
             "IconShadow":"msmarker_shadow.png",
             "IconWidth":"32",
             "IconHeight":"32",
             "ShadowWidth":"59",
             "ShadowHeight":"32"}
    }

GET v1/pins

This method returns a collection of map points objects by map ID.

Request URL
http://api.pinmaps.net/v1/pins?id={id}&apiLogin={apiLogin}&developerKey={developerKey}&userName={userName}&userKey={userKey}
Parameters
apilogin
required		 Developer's API login name
developer key
required		 Developer's API Key
username
required		 The username of the map owner
usekey
required		 The user's API key of the map owner
id
required		 The id of the map containing the map points
Json Response
      [{"MapPointID":5135,
        "MapID":2444,
        "UserName":"PinUser",
        "PointName":"Orlando International",
        "GeocodeAddress":"One Jeff Fuqua Blvd, Orlando, FL 32827, USA",
        "Latitude":"28.4316390",
        "Longitude":"-81.3082862",
        "ZoomLevel":"16",
        "MapType":"G_NORMAL_MAP",
        "PointInfo":"Orlando International Airport (MCO)",
        "DatePosted":"2013-03-15T14:38:54.51",
        "ModifiedOn":null,
        "LinkToGoogleMaps":"maps.google.com/maps?q=28.4316390,-81.3082862&t=m&z=16",
        "Label":"MCO",
        "LabelIsVisible":true,
        "Icon":{"IconID":1,
                "IconName":"dot-red.png",
                "IconShadow":"msmarker_shadow.png","IconWidth":"32",
                "IconHeight":"32",
                "ShadowWidth":"59",
                "ShadowHeight":"32"}
     },{"MapPointID":5136,
        "MapID":2444,
        "UserName":"PinUser",
        "PointName":"Los Angeles International",
        "GeocodeAddress":"1 World Way, Los Angeles, CA 90045, USA",
        "Latitude":"33.9425000",
        "Longitude":"-118.4080560",
        "ZoomLevel":"16",
        "MapType":"G_NORMAL_MAP",
        "PointInfo":"Los Angeles International Airport (LAX)",
        "DatePosted":"2013-03-15T14:41:40.93",
        "ModifiedOn":null,
        "LinkToGoogleMaps":"maps.google.com/maps?q=33.9425000,-118.4080560&t=m&z=16",
        "Label":"LAX",
        "LabelIsVisible":true,
        "Icon":{"IconID":1,
                "IconName":"dot-red.png",
                "IconShadow":"msmarker_shadow.png",
                "IconWidth":"32","IconHeight":"32",
                "ShadowWidth":"59",
                "ShadowHeight":"32"}
     },{"MapPointID":5137,
        "MapID":2444,
        "UserName":"PinUser",
        "PointName":"Minneapolis-St Paul International (MSP)",
        "GeocodeAddress":"Terminal 1-Lindbergh, Glumack Drive, Saint Paul, MN 55111, USA",
        "Latitude":"44.8812340",
        "Longitude":"-93.2031110",
        "ZoomLevel":"16",
        "MapType":"G_NORMAL_MAP",
        "PointInfo":"Minneapolis-St Paul International Airport",
        "DatePosted":"2013-03-15T16:16:25.81",
        "ModifiedOn":null,
        "LinkToGoogleMaps":"maps.google.com/maps?q=44.8812340,-93.2031110&t=m&z=16",
        "Label":"MSP",
        "LabelIsVisible":true,
        "Icon":{"IconID":1,
                "IconName":"dot-red.png",
                "IconShadow":"msmarker_shadow.png",
                "IconWidth":"32",
                "IconHeight":"32",
                "ShadowWidth":"59",
                "ShadowHeight":"32"}
        
     },{"MapPointID":5139,
        "MapID":2444,
        "UserName":"PinUser",
        "PointName":"Detroit Metropolitan Wayne County",
        "GeocodeAddress":"2500 West G Rogell Drive, Detroit, MI 48242, USA",
        "Latitude":"42.2083428",
        "Longitude":"-83.3571754",
        "ZoomLevel":"16",
        "MapType":"G_NORMAL_MAP",
        "PointInfo":"Detroit Metropolitan Wayne County Airport (DTW)",
        "DatePosted":"2013-03-15T16:27:56.207",
        "ModifiedOn":null,
        "LinkToGoogleMaps":"maps.google.com/maps?q=42.2083428,-83.3571754&t=m&z=16",
        "Label":"DTW",
        "LabelIsVisible":true,
        "Icon":{"IconID":1,
                "IconName":"dot-red.png",
                "IconShadow":"msmarker_shadow.png",
                "IconWidth":"32",
                "IconHeight":"32",
                "ShadowWidth":"59",
                "ShadowHeight":"32"}
      }]

POST v1/pin/create

This method creates a single map point on a map and returns the created map point object
Post format: json

Resource URL
http://api.pinmaps.net/v1/pin/create.json
Parameters
DeveloperApiLogin
required		 Developer's API login name
DeveloperApiKey
required		 Developer's API Key
UserName
required		 The username of the map owner
UserApiKey
required		 The user's API key of the map owner
Address
required		 A Street number, Street name, City, State and Zip Code
PointName
required		 The name of the map point
MapID
required		 The id of the map where the map point (marker) will be added
MapType
optional		 The types of maps you can display.
Use only any of these values: ROADMAP, SATELLITE, HYBRID, TERRAIN
If not value or wrong value is supplied a ROADMAP will be used.
PointInformation
optional		 Add any information related about the map point. This text will be displayed on the info window bubble
Label
optional		 A short text that will be displayed under the icon (pin). The maximum lenght is 50 characters
LabelIsVisible
optional		 True or False. Option to show or hide the label
IconId
optional		 The id. Get the list of Icons IDs available here
Json Response
      {"MapPointID":5329,
        "MapID":2444,
        "UserName":"PinUser",
        "PointName":"Newark Liberty International",
        "GeocodeAddress":"1 Brewster Road, Newark, NJ 07114, USA",
        "Latitude":"40.6898700",
        "Longitude":"-74.1782100",
        "ZoomLevel":"16",
        "MapType":"G_SATELLITE_MAP",
        "PointInfo":"Newark International Airport (EWR)",
        "DatePosted":"2013-03-26T21:20:25.907",
        "ModifiedOn":null,
        "LinkToGoogleMaps":"maps.google.com/maps?q=40.6898700,-74.1782100&t=k&z=16",
        "Label":"EWR",
        "LabelIsVisible":true,
        "Icon":{"IconID":1,
                "IconName":"dot-red.png",
                "IconShadow":"msmarker_shadow.png",
                "IconWidth":"32",
                "IconHeight":"32",
                "ShadowWidth":"59",
                "ShadowHeight":"32"}
      }

PUT v1/pin/update

This method updates a single map point and returns the updated map point object
Put format: json

Resource URL
http://api.pinmaps.net/v1/pin/update.json
Parameters
DeveloperApiLogin
required		 Developer's API login name
DeveloperApiKey
required		 Developer's API Key
UserName
required		 The username of the map owner
UserApiKey
required		 The user's API key of the map owner
MapPointID
required		 The id of the map point you want to update
MapID
required		 The id of the map where the map point (marker) will be updated
Address
required		 A Street number, Street name, City, State and Zip Code
PointName
required		 The name of the map point
MapType
optional		 The types of maps you can display.
Use only any of these values: ROADMAP, SATELLITE, HYBRID, TERRAIN
If not value or wrong value is supplied a ROADMAP will be used.
PointInformation
optional		 Add any information related about the map point. This text will be displayed on the info window bubble
Label
optional		 A short text that will be displayed under the icon (pin). The maximum lenght is 50 characters
LabelIsVisible
optional		 True or False. Option to show or hide the label
IconId
optional		 The id. Get the list of Icons IDs available here
Json Response
      {"MapPointID":5329,
        "MapID":2444,
        "UserName":"PinUser",
        "PointName":"Newark Liberty International",
        "GeocodeAddress":"1 Brewster Road, Newark, NJ 07114, USA",
        "Latitude":"40.6898700",
        "Longitude":"-74.1782100",
        "ZoomLevel":"16",
        "MapType":"G_SATELLITE_MAP",
        "PointInfo":"Newark International Airport (EWR)",
        "DatePosted":"2013-03-26T21:20:25.907",
        "ModifiedOn":"2013-03-27T17:14:12.608",
        "LinkToGoogleMaps":"maps.google.com/maps?q=40.6898700,-74.1782100&t=k&z=16",
        "Label":"EWR",
        "LabelIsVisible":true,
        "Icon":{"IconID":1,
                "IconName":"dot-red.png",
                "IconShadow":"msmarker_shadow.png",
                "IconWidth":"32",
                "IconHeight":"32",
                "ShadowWidth":"59",
                "ShadowHeight":"32"}
      }

DELETE v1/pin/destroy

This method deletes a single map point object by map point ID
Delete format: json

Resource URL
http://api.pinmaps.net/v1/pin/destroy.json
Parameters
DeveloperApiLogin
required		 Developer's API login name
DeveloperApiKey
required		 Developer's API Key
UserName
required		 The username of the map owner
UserApiKey
required		 The user's API key of the map owner
MapPointID
required		 The id of the map point you want to remove
Json Response
    {"MapPointID":5144,"UserName":"PinUser"}

GET v1/pins/count

This method returns the total map points count by map ID.

Request URL
http://api.pinmaps.net/v1/pins/count?id={id}&apiLogin={apiLogin}&developerKey={developerKey}&userName={userName}&userKey={userKey}
Parameters
id
required		 The id of the map point count you want to retrieve
apilogin
required		 Developer's API login name
developer key
required		 Developer's API Key
username
required		 The username of the map owner
usekey
required		 The user's API key of the map owner
Json Response
    {"MapID":397,"Count":83}

API Validation

GET v1/credentials/validate

This method validates both the Developer's and the User's API Credentials at the same time.

Request URL
http://api.pinmaps.net/v1/credentials/validate?apiLogin={apiLogin}&developerKey={developerKey}&userName={userName}&userKey={userKey}
Parameters
apiLogin
required		 Developer's API login name
developerKey
required		 Developer's API Key
userName
required		 The username of the map owner
userKey
required		 The user's API key of the map owner
Json Response
    {"valid":true}

GET v1/credentials/developer/validate

This method validate the Developer's API Credentials.

Request URL
http://api.pinmaps.net/v1/credentials/developer/validate?apiLogin={apiLogin}&developerKey={developerKey}
Parameters
apiLogin
required		 Developer's API login name
developerKey
required		 Developer's API Key
Json Response
       {"DeveloperApiLogin":"[MyAppLoginName]",
        "DeveloperApiKey":"[devapikey]",
        "DateCreated":"2013-03-18T09:37:34.683",
        "IsActive":true
       }

GET v1/credentials/user/validate

This method validate the User's API Credentials.

Request URL
http://api.pinmaps.net/v1/credentials/user/validate?userName={userName}&userKey={userKey}
Parameters
userName
required		 The username of the map owner
userKey
required		 The user's API key of the map owner
Json Response
       {"UserApiKey":"[userapikey]",
        "UserName":"[MyPinmapsUserName]",
        "DateCreated":"2013-03-18T14:10:27.43",
        "IsActive":true
       }

Response Codes

API Errors & Response Codes

The Pinmaps API attempts to return appropriate HTTP status codes for most of the requests; however, it is possible that there will be some instances where you will not get a response code.

Codes
200 OK - The request succeeded and that the requested information is in the response.
201 Created - The request has been accepted for further processing.
400 BadRequest - BadRequest indicates that the request could not be understood by the server.
401 Unauthorized - Unauthorized indicates that the requested resource requires authentication.
406 NotAcceptable - Will not accept any of the available representations of the resource.
500 InternalServerError - Something is broken and the server cannot process the request.
404 NotFound - The requested resource does not exist on the server.

Code Samples

.NET CSharp

Pinmaps.netApiClient Source Code on GitHub
https://github.com/Pinmaps/Pinmaps.netApiClient