{"id":44018518,"url":"https://github.com/label84/php-nederland-postcode","last_synced_at":"2026-02-07T16:04:51.766Z","repository":{"id":328473515,"uuid":"1110176434","full_name":"Label84/php-nederland-postcode","owner":"Label84","description":"Integrate Dutch address validations into your PHP application using the Nederland Postcode API. ","archived":false,"fork":false,"pushed_at":"2025-12-13T10:49:15.000Z","size":28,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-15T00:59:18.201Z","etag":null,"topics":["php","php-package"],"latest_commit_sha":null,"homepage":"https://nederlandpostcode.nl","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Label84.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-04T20:23:55.000Z","updated_at":"2025-12-13T10:49:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Label84/php-nederland-postcode","commit_stats":null,"previous_names":["label84/php-nederland-postcode"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Label84/php-nederland-postcode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Label84%2Fphp-nederland-postcode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Label84%2Fphp-nederland-postcode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Label84%2Fphp-nederland-postcode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Label84%2Fphp-nederland-postcode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Label84","download_url":"https://codeload.github.com/Label84/php-nederland-postcode/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Label84%2Fphp-nederland-postcode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29199519,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-07T14:35:27.868Z","status":"ssl_error","status_checked_at":"2026-02-07T14:25:51.081Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["php","php-package"],"created_at":"2026-02-07T16:04:45.881Z","updated_at":"2026-02-07T16:04:51.759Z","avatar_url":"https://github.com/Label84.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nederland Postcode PHP\n\n![Nederland Postcode API](./docs/nederlandpostcodeapi.png)\n\nNederland Postcode PHP makes it easy to integrate Dutch address validations into your PHP application using the [Nederland Postcode API](https://nederlandpostcode.nl).\n\nRegister for free to obtain a **test API key** at [nederlandpostcode.nl](https://nederlandpostcode.nl) to get started.\n\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Address Endpoint](#address-endpoint)\n    - [Single Address](#single-address)\n    - [Multiple Addresses](#multiple-addresses)\n  - [Energy Label Endpoint](#energy-label-endpoint)\n  - [Quota Endpoint](#quota-endpoint)\n- [Error Handling](#error-handling)\n\n## Requirements\n\n- PHP 8.2+\n\n## Installation\n\nInstall the package via Composer:\n\n```bash\ncomposer require label84/php-nederland-postcode\n```\n\n## Usage\n\n```php\nrequire_once __DIR__ . '/vendor/autoload.php';\n\nuse Label84\\NederlandPostcode\\NederlandPostcodeClient;\n\n$client = new NederlandPostcodeClient(\n    key: 'npa_live_XXX',\n);\n\ntry {\n    $address = $client-\u003efind(\n        postcode: '1118BN',\n        number: 800,\n        attributes: ['coordinates'],\n    );\n} catch (NederlandPostcodeException $exception) {\n    // handle exception\n}\n\necho $address-\u003estreet; // Schiphol Boulevard\necho $address-\u003ecoordinates-\u003elatitude; // 52.30703569036619\n```\n\n### Address Endpoint\n\nThe address endpoint allows you to fetch address information from the Nederland Postcode API.\n\nYou can search addresses using either the `find` method for a single address or the `list` method for multiple addresses. The `find` method will throw an exception if no address is found or if multiple addresses are found for the given postcode and house number (ie. when the house number has multiple additions like A, B, C, etc.).\n\nThe following optional attributes can be requested to be included in the response:\n\n- `coordinates`: Includes latitude and longitude of the address.\n\n#### Single Address\n\nTo fetch a single address for a given postcode and house number, you can use the `find` method.\n\nThe `postcode` and `number` parameters are required. The `addition` parameter is optional.\n\n```php\nuse Label84\\NederlandPostcode\\NederlandPostcodeClient;\n\n$client = new NederlandPostcodeClient(\n    key: 'npa_live_XXX'\n);\n\n$address = $client-\u003efind(\n    postcode: '1118BN',\n    number: 800,\n    addition: null,\n    attributes: ['coordinates'],\n);\n```\n\nThis will return an `Address` object like this:\n\n```php\nAddress {\n    postcode: \"1118BN\",\n    number: 800,\n    addition: null,\n    street: \"Schiphol Boulevard\",\n    city: \"Schiphol\",\n    municipality: \"Haarlemmermeer\",\n    province: \"Noord-Holland\",\n    coordinates: Coordinates {\n        latitude: 52.30528553688755,\n        longitude: 4.750645160863609\n    }\n}\n```\n\nWhen no address is found for the given postcode and number, an `AddressNotFoundException` is thrown. If multiple addresses are found, a `MultipleAddressesFoundException` is thrown.\n\n#### Multiple Addresses\n\nTo fetch multiple addresses for a given postcode and house number, you can use the `list` method.\n\nThe `postcode` and `number` parameters are required. The `addition` parameter is optional.\n\n```php\nuse Label84\\NederlandPostcode\\NederlandPostcodeClient;\n\n$client = new NederlandPostcodeClient(\n    key: 'npa_live_XXX'\n);\n\n$addresses = $client-\u003elist(\n    postcode: '1015CN',\n    number: 10,\n    addition: null,\n    attributes: ['coordinates'],\n);\n```\n\nThis will return an `AddressCollection` like this:\n\n```php\nAddressCollection {\n    items: [\n        Address {\n            postcode: \"1015CN\",\n            number: 10,\n            addition: \"A\",\n            street: \"Keizersgracht\",\n            city: \"Amsterdam\",\n            municipality: \"Amsterdam\",\n            province: \"Noord-Holland\",\n            country: \"Nederland\",\n            coordinates: Coordinates { ... }\n        },\n        Address {\n            postcode: \"1015CN\",\n            number: 10,\n            addition: \"B\",\n            street: \"Keizersgracht\",\n            ...\n        }\n    ]\n}\n```\n\n### Energy Label Endpoint\n\nThe energy label endpoint allows you to fetch energy label information for a given postcode and house number (with optional addition).\n\n```php\nuse Label84\\NederlandPostcode\\NederlandPostcodeClient;\n\n$client = new NederlandPostcodeClient(\n    key: 'npa_live_XXX'\n);\n\n$energyLabels = $client-\u003eenergyLabels()-\u003eget(\n    postcode: '1118BN',\n    number: 800,\n    addition: null,\n);\n```\n\nThis will return an `EnergyLabelCollection` like this:\n\n```php\nEnergyLabelCollection {\n    items: [\n        EnergyLabel {\n            postcode: \"1118BN\",\n            number: 800,\n            addition: null,\n            street: \"Schiphol Boulevard\",\n            city: \"Schiphol\",\n            inspectionDate: DateTime(\"2022-08-02\"),\n            validUntilDate: DateTime(\"2032-08-02\"),\n            constructionType: \"utiliteitsbouw\",\n            buildingType: null,\n            energyLabel: \"A+++\",\n            maxEnergyDemand: 98.4,\n            maxFossilEnergyDemand: 55.48,\n            minRenewableShare: 55.3\n        }\n    ]\n}\n```\n\n### Quota Endpoint\n\nThe quota endpoint allows you to check your current API usage and limits. This endpoint does not increment your usage count.\n\n\u003e [!NOTE]\n\u003e Values may lag behind the actual usage. They're cached for up to five minutes, so the `used` and `limit` numbers might not be fully up-to-date.\n\n```php\nuse Label84\\NederlandPostcode\\NederlandPostcodeClient;\n\n$client = new NederlandPostcodeClient(\n    key: 'npa_live_XXX'\n);\n\n$quota = $client-\u003eusage();\n```\n\nThis will return an `Quota` object like this:\n\n```php\nQuota {\n    used: 1500,\n    limit: 10000,\n}\n```\n\n## Error Handling\n\nThe package throws a `NederlandPostcodeException` for any errors encountered during the API request. You can catch this exception to handle errors gracefully:\n\n```php\nuse Label84\\NederlandPostcode\\Exceptions\\NederlandPostcodeException;\n\n$client = new NederlandPostcodeClient(\n    key: 'npa_live_XXX'\n);\n\ntry {\n    $addresses = $client-\u003efind(\n        postcode: 'INVALID',\n        number: 123,\n        addition: null,\n    );\n} catch (NederlandPostcodeException $exception) {\n    // handle error\n}\n```\n\nWhen calling the `find` method, if no address is found, an `AddressNotFoundException` is thrown. If multiple addresses are found, a `MultipleAddressesFoundException` is thrown.\n\nWhen a network or HTTP error occurs during the API request, a `NederlandPostcodeRequestException` is thrown, which wraps the original `RequestException`.\n\n## Contributing\n\n```bash\n./vendor/bin/phpstan analyse\n```\n\n```bash\n./vendor/bin/phpunit\n```\n\n## License\n\n[MIT](https://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flabel84%2Fphp-nederland-postcode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flabel84%2Fphp-nederland-postcode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flabel84%2Fphp-nederland-postcode/lists"}