diff --git a/README.md b/README.md
index 9d82f52..c322ed6 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,104 @@
-# tfl_status_2
\ No newline at end of file
+# pydantic tfl api
+
+I originally used [TfL-python-api](https://github.com/dhilmathy/TfL-python-api) by @dhilmathy but that verision depends on the [msrest](https://github.com/Azure/msrest-for-python) package, which has been deprecated for 2+ years. I have created this package to replace it, using pydantic and requests.
+
+This API returns data from the TfL API in a more pythonic way, using pydantic models. It's a thin wrapper around the TfL API, so you can use the TfL API documentation to see what data is available.
+
+## Installation
+
+```bash
+pip install pydantic-tfl-api
+```
+
+## Usage
+
+Uses Pydantic so you can use the `model_dump_json()` method to see the data returned by the API. See [Pydantic documentation](https://docs.pydantic.dev/latest/) for more help
+
+```python
+from tfl.client import Client
+from tfl.api_token import ApiToken
+
+app_id = 'APPLICATION ID'
+app_key = 'APPLICATION KEY'
+
+token = ApiToken(app_id, app_key)
+
+client = Client(token)
+print (client.get_line_meta_modes().model_dump_json())
+print (client.get_lines(mode="bus")[0].model_dump_json())
+print (client.get_lines(line_id="victoria")[0].model_dump_json())
+```
+## Class structure
+
+The Pydantic classes are in the `tfl.models` module. The `tfl.client` module contains the `Client` class, which is the main class you will use to interact with the API.
+
+Pydantic models are used to represent the data returned by the TfL API. There is a circular reference in the TfL API, so I handled this in the `StopPoint` model to load the `Line` model only after `StopPoint` is fully loaded. Here's a visualisation of the Pydantic models:
+
+```mermaid
+classDiagram
+    direction LR
+    class AffectedRoute
+    class RouteSectionNaptanEntrySequence
+    AffectedRoute ..> RouteSectionNaptanEntrySequence
+
+    class PredictionTiming
+    class Prediction
+    Prediction ..> PredictionTiming 
+
+    class Crowding
+    class PassengerFlow
+    class TrainLoading
+    Crowding ..> PassengerFlow
+    Crowding ..> TrainLoading
+
+    class Identifier
+    Identifier ..> Crowding
+
+    class OrderedRoute
+    class RouteSequence
+    class MatchedStop
+    RouteSequence ..> MatchedStop
+    RouteSequence ..> OrderedRoute
+
+    class ApiError
+    class Mode
+
+
+    class Line
+    Line ..> Disruption
+    Line ..> LineStatus
+    Line ..> RouteSection
+    Line ..> ServiceType
+    Line ..> Crowding
+
+    class RouteSection
+    class ServiceType
+    class ValidityPeriod
+    class LineStatus
+    class Disruption
+
+    class StopPoint
+    class StopPointsResponse
+    class AdditionalProperties
+    class StopPointsResponse
+    class LineModeGroup
+    class LineGroup
+
+
+
+    LineStatus ..> ValidityPeriod
+    LineStatus ..> Disruption
+
+    Disruption ..> AffectedRoute
+    MatchedStop ..> Identifier 
+
+    RouteSectionNaptanEntrySequence ..> StopPoint
+
+    StopPoint ..> LineGroup
+    StopPoint ..> LineModeGroup
+    StopPoint ..> AdditionalProperties
+    StopPoint ..> Line
+    StopPointsResponse ..> StopPoint
+
+
+```
\ No newline at end of file