Skip to main content

Projects: Get project data

Easy PV and Heatpunk generate a full bill of materials for a project, and for our UK and Ireland sites you can very quickly place an order for the components from Midsummer. So you may like to import the shopping cart into your application and display an ordering link. Users love the ease of ordering all the kit for an installation.

The cart is based on the bill of materials generated by the software for a given project. The bill of materials for the project is refreshed every time the overview page of the project is opened by a user in Easy PV or Heatpunk.

GET /projects/data

Use this endpoint to fetch project data.

Authentication

Endpoint:  

GET https://[DOMAIN]/api/v1/projects/data

Headers:

  • X-API-KEY: YOUR_API_KEY     (Replace YOUR_API_KEY with your actual API key.)

Request structure

Every request to create a new project must include the following:

ID: The id of the project as a number.

User email: The userEmail should be a valid email address of an Easy PV Pro team member who has access to the project.

Example API request and response
Example API Request

Below is an example using curl that demonstrates how to create a project with the required fields:

curl -X POSTGET 'https://easy-pv.co.uk/api/v1/projects/data' \
     -H 'accept: application/json' \
     -H 'X-API-KEY: YOUR_API_KEY'
Response

A successful call returns a projectData object which will include core project data plus cart and midsummerOrderLink arrays.

The projectData object will include core project and customer information. For example:

"projectData": {
        "lat": 52.2305742,
        "lng": 0.14036,
        "zoom": 19,
        "address": "101 Kings Hedges Rd, Cambridge , UK",
        "postcode": "CB4 2QD",
        "dateCreated": "2024-10-02 17:42:45",
        "dateModified": "2024-10-17 14:11:58",
        "projectName": "Sample Project",
        "customerName": "Testing Testington",
        "includeTerrain": false,
        "MCSSiteVisitDisclaimer": false,
        "geography": {
            "altitude": 12,
            "distance": "2to20",
            "hillSlope": null,
            "hillZone": null,
            "terrain": "country",
            "topography": "no",
            "windZone": 3,
            "snowZone": 2
        },
        "projectType": "three-d-model",
        "magicMode": true,
        "customerPhone": "0777 777 777",
        "customerEmail": "testing@testington.com",
        "userID": "19380",
        "status": "Lead",
        "mapImagery": {
            "selectedType": "orthorectified",
            "orthorectified": {
                "fileId": "rG2G25",
                "rotationUsed": 2.2618198,
                "radius": 48.137703120171004
            }
        },
        "projectID": "986206",
        "MCSDisclaimer": true,
        "MCSReservedCapacity": 50,
        "MCSAdditionalConsumption": 0,
        "MCSConsumption": "3500",
        "MCSOccupancy": "home all day",
        "totalConsumption": 3500,
        "selfConsumption": 980.7616984962381,
        "threeDModelSettingsViewDirection": [
            -4.3836904133806645,
            -6.107308078177546,
            10.644089349920092,
            0.054191298862051804,
            2.2301402617071955,
            2.241462631675495
        ],
        "threeDSnapshots": [
            "l6Jskm"
        ],
        }

The cart array contains the full bill of materials as a JSON object. This contains details of all the products that have been specified in the project. For example:

"cart": [
            {
                "name": "Jinko Tiger Neo 440W N-Type All Black Mono solar panel",
                "qty": 6,
                "item": 84,
                "line": 504,
                "dbID": "5265",
                "availableFrom": {
                    "midsummer": {
                        "ID": "5265",
                        "price": 504
                    }
                }
            },
            {
                "name": "Growatt MIN 10000 TL-X2 Three MPPT 1ph inverter",
                "qty": 1,
                "item": 1050,
                "line": 1050,
                "dbID": "5397",
                "availableFrom": {
                    "midsummer": {
                        "ID": "5397",
                        "price": 1050
                    }
                }
            },
            {
                "name": "Giv.AC 3.0 inverter",
                "qty": 1,
                "item": 933.8,
                "line": 933.8,
                "dbID": "3040",
                "availableFrom": {
                    "midsummer": {
                        "ID": "3040",
                        "price": 933.8
                    }
                }
            },
            {
                "name": "GivEnergy 5.2kWh LiFePO4 Battery",
                "qty": 1,
                "item": 1796.2,
                "line": 1796.2,
                "dbID": "4284",
                "availableFrom": {
                    "midsummer": {
                        "ID": "4284",
                        "price": 1796.2
                    }
                }
            },
            ]

The midsummerOrderLink is a URL that can be used to order everything needed for a project from Midsummer. For example:

"midsummerOrderLink": "https://midsummerwholesale.co.uk/upload/?order=eyJpdGVtcyI6eyI3OCI6eyJ0aXRsZSI6IkxhYmVsIHNoZWV0IiwicXR5IjoyfSwiMzgwIjp7InRpdGxlIjoiMTAwbSByZWVsIG9mIDZtbTIgc29sYXIgY2FibGUiLCJxdHkiOjF9LCIxNzc5Ijp7InRpdGxlIjoiTUM0IDZtbSBDb25uZWN0b3IgUGFpciIsInF0eSI6NH0sIjIyOTgiOnsidGl0bGUiOiJUaWdvIFJldHJvZml0IEZyYW1lIE1vdW50ZWQgT3B0aW1pc2VyIFRTNC1BLU8iLCJxdHkiOjZ9LCIyNTg2Ijp7InRpdGxlIjoiRmFzdGVuc29sIHJhaWwgc3BsaWNlIiwicXR5Ijo2fSwiMjU4NyI6eyJ0aXRsZSI6IkZhc3RlbnNvbCByYWlsIGJvbHQiLCJxdHkiOjZ9LCIyNTk0Ijp7InRpdGxlIjoiRmFzdGVuc29sIHBvcnRyYWl0IGZsYXQgdGlsZSByb29mIGhvb2siLCJxdHkiOjI0fSwiMjgxMiI6eyJ0aXRsZSI6IkJhdHRlcnkgSGF6YXJkIFdhcm5pbmcgTGFiZWwgUGFjayIsInF0eSI6MX0sIjI4MTQiOnsidGl0bGUiOiIqKk5FVCoqIEVtbGl0ZSBCaS1kaXJlY3Rpb25hbCBNZXRlciBFQ0EyLm4qIiwicXR5IjoxfSwiMzA0MCI6eyJ0aXRsZSI6Ikdpdi5BQyAzLjAgaW52ZXJ0ZXIiLCJxdHkiOjF9LCIzMDQ2Ijp7InRpdGxlIjoiR2l2RW5lcmd5IFdpRmkgRG9uZ2xlIiwicXR5IjoxfSwiMzE1NyI6eyJ0aXRsZSI6IkZhc3RlbnNvbCBibGFjayB1bml2ZXJzYWwgY2xhbXAiLCJxdHkiOjE4fSwiMzU4NCI6eyJ0aXRsZSI6Ikdyb3dhdHQgU2hpbmVXaUZpLVgiLCJxdHkiOjF9LCIzNjU1Ijp7InRpdGxlIjoiR2l2RW5lcmd5IERDIE1pbmlhdHVyZSBDaXJjdWl0IEJyZWFrZXIgKE1DQikiLCJxdHkiOjJ9LCI0Mjg0Ijp7InRpdGxlIjoiR2l2RW5lcmd5IDUuMmtXaCBMaUZlUE80IEJhdHRlcnkiLCJxdHkiOjF9LCI0NDg0Ijp7InRpdGxlIjoiR2l2RW5lcmd5IFBsdWcgdG8gTHVnIENhYmxlIChHZW4zKSIsInF0eSI6MX0sIjQ0OTMiOnsidGl0bGUiOiJBQyBpc29sYXRvciAtIElNTyAtIDIwQSA0LXBvbGUiLCJxdHkiOjJ9LCI0NTU1Ijp7InRpdGxlIjoiQUMgaXNvbGF0b3IgLSBJTU8gLSA2M0EgNC1wb2xlIiwicXR5IjoyfSwiNTEwNSI6eyJ0aXRsZSI6IlJ1YmJlciBHcm9tbWV0IGZvciBHZW4zIEludmVydGVyIFBsdWcgQ2FibGVzIiwicXR5IjoxfSwiNTI2NSI6eyJ0aXRsZSI6IkppbmtvIFRpZ2VyIE5lbyA0NDBXIE4tVHlwZSBBbGwgQmxhY2sgTW9ubyBzb2xhciBwYW5lbCIsInF0eSI6Nn0sIjUyNzYiOnsidGl0bGUiOiJGYXN0ZW5zb2wgc2lsdmVyIHJhaWwgMzU1MG1tIiwicXR5Ijo3fSwiNTM5NyI6eyJ0aXRsZSI6Ikdyb3dhdHQgTUlOIDEwMDAwIFRMLVgyIFRocmVlIE1QUFQgMXBoIGludmVydGVyIiwicXR5IjoxfSwiNTU2MSI6eyJ0aXRsZSI6IkdpdkVuZXJneSBHRU0xMjBDVCBNb2RidXMgRW5lcmd5IE1ldGVyIiwicXR5IjoxfSwiIjp7InRpdGxlIjoiTWF0dCBTY2FmZm9sZGluZyBvdmVyIGNvbnNlcnZhdG9yeSIsInF0eSI6MX0sIjI2NDgjMzU5MCI6eyJ0aXRsZSI6IkZhc3RlbnNvbCBibGFjayBlbmQgY2FwIiwicXR5IjoxMn19LCJ0cmFjZSI6eyJzcmMiOiJlYXN5LXB2IiwibW9kZSI6InVrIiwicHJvamVjdElEIjoiOTg2MjA2In19",

Customise cart and order links

If you wish to modify the bill of materials for a project and create your own cart object, you can use this to generate a custom order link. If you do this, you can also add some additional parameters such as a delivery address or order reference to the order (see instructions in the next section). 

In its simplest form, an order can be just an object with an 'items' property. For each item, specify the the products by providing the product ID and the quantity required.

const order = {
    "items": {
        "2586": {
            "qty": 99
        },
       "4258": {
            "qty": 99
       }
   }
}

Here is a more complex order, with a shipping address, despatch date and reference:

const order = {
    "items": {
        "2586": {
            "qty": 99
        },
   },
  "deliveryOption": "standard",
  "shippingAddress": {
    "postcode": "CB24 6AZ",
    "add1": "Midsummer Energy",
    "add2": "Cambridge Road Industrial Estate",
    "add3": "Milton",
    "add4": "",
    "email": "sales@midsummerenergy.co.uk",
    "phone": "01223 858414",
    "firstname": "Andy",
    "lastname": "Rankin"
  },
  "despatchDate": "2023-02-08",
  "reference": "trial order"
}

Once you have created the JSON object containing the products required for the project you can create an order string by following these steps:

  1. Stringify the object
  2. Base64 encode the result of the stringified object
  3. URL encode the base64 encoded string
  4. Append your string to the following URL to create your custom order link https://midsummerwholesale.co.uk/upload?order=[result string]

In JavaScript the function you need to generate an order is:

 function createOrderLink(order) {
      return "https://midsummerwholesale.co.uk/upload?order="+encodeURIComponent(btoa(JSON.stringify(order)))
  }
Back to top